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Resource macro disassembler — NEW VERSION! 

Resource V5 is an intelligent interactive disassembler ior the Amiga programmer. ReSource V5 is blindingly fast, disassembling literally 
hundreds of thousands of lines per minute from executable files, binary files, disk tracks, or directly from memory. Full use is made of the Amiga 
windowing environment, and there are over 900 functions to make disassembling code easier and more thorough than its ever been. 

Virtually all V2.0 Amiga symbol bases are available at the touch of a key. In addition, you may create your own symbol bases, Base-relative 
addressing, using any address register, is supported for disassembling compiled programs. All Amiga hunk types are supported for code scan. 

Resource V5 runs on any 680x0 CPU, but automatically detects the presence of an 020/030 CPU and runs faster routines if possible. 
ReSource VS understands 68030 instructions and supports the new M68000 Family assembly language syntax as specified by Motorola for the 
new addressing modes used on the 020/030 processors. ReSource V5 and Macro68 are among the few Amiga programs now available that 
provide this support. Old syntax is also supported as a user option. 

An all new online help facility featuring hypertext word indexing is included. This enables you to get in-depth help about any function at the touch 
of a keyl ReSource V5 includes a new, completely rewritten manual featuring two tutorials on disasssembly, and comprehensive instructions for 
utilizing the power in ReSource VS. 

Resource V5 will enable you to explore the Amiga. Find out how your favorite program works. Fix bugs in executables Examine your own 
compiled code. 

"If you're serious about disassembling code, look no further I" 
ReSource VS requires V1 .3 or later of the Amiga OS, and at least 1 megabyte of ram. ReSource VS supercedes all previous versions. 



Suggested retail price: US$150 



Macro68 macro assembler— NEW VERSION! 

Macro68 is the mosf powerful assembler for the entire line of Amiga personal computers. 



Buy Macro68 

and ReSource 

together and get 

$30 off! 




Macro68 supports the entire Motorola M68000 Family including the MC68030 and MC68040 CPUs, MC68881 and MC68882 FPUs and 
MC68851 MMU. The Amiga Copper is also supported, eliminating the need for tedious hand coding of 'Copper Lists'. 

This fast, multi-pass assembler supports the new Motorola M68000 Family assembly language syntax, and comes with a utility to convert 
old-style syntax source code painlessly. The new syntax was developed by Motorola specifically to support the addressing capabilities of the 
new generation of CPUs. Old-style syntax is also supported, at slightly reduced assembly speeds. 

Most features of Macro68 are limited only by available memory. It also boasts macro power unparalleled in products of this class. There are 
many new and innovative assembler directives. For instance, a special structure offset directive assures maximum compatibility with the Amiga's 
interface conventions. A frame olfset directive makes dealing with stack storage easy. Both forward and backward branches, as well as many 
other instructions, may be optimized by a sophisticated N-pass optimizer. Full listing control, including cross-referenced listings, is standard. A 
user-accessible file provides the ability to customize directives and run-time messages from the assembler. 

Macro68 is fully re-entrant, and may be made resident. An AREXX™ interface provides "real-time" communication with the editor of your choice. A 
number of directives enable Macro68 to communicate with AmigaDos™. External programs may be invoked on either pass, and the results interpreted. 
Possibly the most unique feature of MacroSB is the use of a shared-library, which allows resident preassembled include files for incredibly fast assemblies. 

Macro68 is compatible with the directives used by most popular assemblers, Output file formats include executable object, linkable object, 
binary image, and Motorola S records. Macro68 requires at least 1 meg of memory. 

Suggested retail price: USS150 
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First off, I should attend to some unfinished business 
from last issue. In it 1 promised we would be starting "a 
(currently unnamed) column to cover introductory Amiga 
programming concepts in BASIC and C." We now have a 
name and a column: Turn to page 14, and you'll find the 
first installment of "Beginner's Connection." Each issue, 
veteran Commodore author Jim Butterfield will introduce 
you to new system routines and Amiga programming 
issues, showing you how to access these functions from 
both Amiga Basic and C. We hope this helps not only pro- 
grammers new to the Amiga, but also BASIC programmers 
who want to make the switch to C. 

As we sorted through the letters and e-mail trying to find 
the best focus for "Beginner's Connection," we discovered 
another neglected but rather vocal group — authoring sys- 
tem programmers. In a flurry of holiday goodwill, we 
instituted yet another new column — "Authoring 
Solutions." Over the course of the year, we will cover all of 
the major authoring systems — AmigaVision, CanDo, Foun- 
dation, and VIVA — concentrating on only one per column. 
Each issue, an expert on the highlighted system will ex- 
plain under- or undocumented features and help you im- 
prove your scripts. We kick off the column (on page 24) 
with AmigaVision tips from John Gerlach of IMSATT, 
AmigaVision 's creators. 

All the talk and excitement about authoring systems 
lately makes me wonder where programming is going: 

• Will the "anybody can do it" style of high-level, icon- 
based authoring move in from the fringe to relegate low- 
level languages such as C and assembly to "for traditional- 
ists only" status? 

• Should the Tech journal, like Commodore, embrace 
AmigaVision rather than Amiga Basic as the tool of choice 
for beginners? 

• Should we have started only "Authoring Solutions" 
instead of two new columns? 

For now I think the answer is no to all three questions, 
which I suppose marks me as command-based traditional- 
ist instead of an iconified free thinker. 

How do you feel on the authoring question — are icon- 
based languages the coming standard or just a shortcut for 
people who don't want to learn "real" programming? Drop 
me a line (The AmigaWorld Tech Journal, 80 Elm St., Peter- 
borough, NH 03458, or llaflamme on BIX) and let me know. 
You ask for it, and we'll cover it. ■ 
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Under the Lid: 
The Amiga Custom Chip Set 

What do Agnus, Denise, and Paula 
really do all day? 



By Dave Haynie 



WHEN THE AMIGA 1000 was introduced, it was hailed 
as a true innovation in microcomputers. The WIMP inter- 
face, multitasking, and 68000 processor were all state of the 
art, but the main reason for excitement was the system's so- 
phisticated set of three custom chips — Agnus, Denise, and 
Paula. After several generations of Amigas, the names of the 
custom chips have become household names, but the details 
of their operation are still in need of explanation. 

MODERN ARCHITECTURE 

Most computers have a variety of basic needs: video dis- 
play, sound, floppy disk, serial port, and so on. These needs 
are often met with a variety of specific puipose parts, as in 
the run of the mill IBM clone. While that approach does work, 
the result is often more expensive with a much less cohesive 
architecture than a machine designed from the ground up to 
act as a system. The Amiga custom chips represent such an 
integrated-support chip design. 

The Amiga chip set's rather novel architecture integrates 
the basics of video display, sound generation, floppy-disk 
I/O, serial-port I/O, and a few other system-support func- 
tions into three full custom chips. Based on the gate density 
available using full custom LSI (even back in 1985), howev- 
er, most of these items are enhanced beyond the equivalent 
function in traditional computers. For example, a bit-image 
manipulation device (the Blitter) and display-list coproces- 
sor (the Copper) were added to support the basic video dis- 
play. Also, an eight-channel sprite engine makes the display 
of the pointer and other small moving icons much less CPU 
intensive. Floppy-disk I/O is driven by a DMA channel, 
which is very important in a multitasking environment. Sim- 
ilarly, the sound is based on digital-to-analog conversion, 
rather than the simple multiple-voice ADSR chips typical of 
personal computers with integrated sound. Plus, the chip set 
supports four of these audio channels, each with an attached 
DMA channel that make them as easy to use as classic 
"sound chips." Along with all this comes a "free" DRAM 
controller. 

THE CHIP BUS 

To understand the specifics of the novel architecture of the 
three custom chips, which essentially function as one, you 
should start with the basic bus design of the Amiga chips. Fig- 
ure 1 is a very simplified block diagram of both the chip-in- 
terconnect and internal chip functions. Considered a com- 
puter system unto themselves, the three chips function like 
a traditional microprocessor system. The core of this system 
is the address-generator chip, Agnus. (The other two are the 
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display-generator chip, Denise, and the ports and audio chip, 
Paula.) Like a microprocessor, Agnus is responsible for gen- 
erating addresses on the address bus, managing data on a 
data bus, and controlling additional bus management sig- 
nals. Agnus connects directly to a 16-bit chip-data bus and a 
multiplexed (to allow direct connection to DRAM) chip-ad- 
dress bus up to ten bits wide. The chip bus is a pure syn- 
chronous, deterministic bus; there are no start or stop strobes, 
no wait states, and thus no need for any real bus-control lines 
generated by Agnus. 

The Agnus chip, however, is not simply addressing mem- 
ory with each bus cycle. Unlike a traditional microprocessor, 
which must manage a small number of general purpose reg- 
isters, Agnus manages many special-purpose registers or en- 
tities represented as registers, which can be located in one or 
both of the other custom chips. So along with a RAM address, 
each cycle gets a "register" address, on a separate eight-bit- 
wide bus called the register address, or RGA, bus. The value 
on the RGA bus usually indicates the access of a particular 
chip-bus register, although in some cases the value actually 
represents a synchronization strobe, DMA channel FIFO ac- 
cess, or miscellaneous command, such as memory refresh or 
NOP. Because all Amiga registers are either read-only or 
write-only, the RGA address also implies the direction of 
data flow, which is generally between an RGA-defined reg- 
ister and DRAM, or DRAM and a register location. 

CHIP-BUS DMA 

One of the highly touted features of the Amiga's custom 
chip system is its multiple DMA channels. Not only are there 
a large number of DMA channels, but DMA on the Amiga 
chip bus works quite differently than traditional micropro- 
cessor DMA. In most microprocessor systems, high-band- 
width I/O devices may be married to DMA controllers of 
some form. A DMA controller makes I/O data transfers more 
efficient, because it can handle the jobs of I/O polling and 
data transfer to memory, freeing up the host CPU for other 
activity. Generally, such a DMA controller queues up a rea- 
sonable amount of data in a FIFO, requests the microproces- 
sor bus, receives a bus grant, transfers all data as bus master, 
then relinquishes the bus. 

While that system works just fine in the nondeterministic 
world of the traditional microprocessor, it can't work on the 
Amiga chip bus. Amiga DMA channels manage such pro- 
cesses as video display, audio playback, and disk I/O. If any 
of these does not happen exactly when it's supposed to, the 
result is a failure of some kind. So on the Amiga chip bus, 
much of the DMA is not truly arbitrated. It's preallocated to 
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"slots" based on the video raster, as il- 
lustrated in Figure 2. Agnus simply gen- 
erates the proper RGA command at the 
appropriate slot, and the correct DMA 
channel is accessed. Not only does this 
allow the chip bus to be totally deter- 
ministic, but also it keeps all address gen- 
eration in Agnus, simplifying the design 
of the other chips on the bus. 

Each slot indicated is approximately 
560ns long and consists of two possible 
chip bus cycles. The first half of the slot, 
the "even" half, is usually devoted to a 
fixed allocation, such as refresh or audio 
DMA. Fixed DMA only takes place if 
it's enabled. For example, sprites that 
aren't turned on don't get cycles, and 
video fetch uses only the cycles its dis- 
play mode requires. Video and sprites 
can actually overlap, as sprites are sub- 
tracted to permit overscan video fetch. 
Any free cycles are made available to 
nondeterministic chip resources. The 
first of these to get cycles is the Copper, then the Blitter, and 
finally, the host-processor access gate (more on that later), 
based on need. 

Chip DMA cycles are generated based on the register set- 
up of the various DMA controllers in Agnus. Consider a sim- 
ple four-bitplane hi-res display. This requires Agnus's bit- 
plane-control registers to be set properly for the chosen 
display, the bitplane DMA-fetch control to be enabled, and 
finally, four bitplane pointers to be loaded into Agnus's bit- 
plane-fetch controller. Bitplane pointers are loaded via a Cop- 
per list, so Copper DMA must also be enabled. At the start 
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Figure 1. The diip-inlerconnect and Internal chip functions of the Amiga cuslom chip set. 



of a display, before the visible portion, Agnus forces a "jump" 
to the primary Copper list pointer, which is given by a 32-bit 
Agnus-resident register pair, COP1LC ($080). The Copper 
fetches its first instruction, indicated by COPINS ($08C) on 
the RGA bus, which in this case is a move to BPL1PTH ($0E0), 
the high half of the first bitplane pointer. The next RGA cy- 
cle is the actual move, with $E0 on the RGA bus, the high half 
of the bitplane data value on the data bus. The Copper then 
sequences through fetches for BPL1PTL, then the high/low 
halves of BPL2PT, BPL3PT, and BPL4PT. Note that the Cop- 
per, like the 68000 (but not the Blitter), may access the chip i 
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bus only on "odd" chip-bus cycles, so in this case, four bit- 
plane pointers are loaded by the Copper in 16 total roughly- 
280ns cycles, or about 4.48 microseconds. In a real-iife Cop- 
per list, the bitplane configuration and color palette would 
most likely also be controlled by the Copper list. Once the bit- 
planes are set up, this example is finished with the Copper, 
so it'll end the Copper list with a wait for end-of-display. 

Once the visible portion of the display is encountered, dis- 
play DMA must take place. As usual, the scan line starts with 
memory refresh, optional disk, audio, and sprite DMA. The 
first and sometimes second refresh cycles have horizontal 
line strobe values ($038-$03e) on the RGA bus, the remain- 
ing refresh cycles are NOPs from the RGA viewpoint. Disk, 
audio, and sprite all have DMA chan- 
nels on RGA when necessary, all based 
on DMA control and enable registers 
in Agnus. Bitplane data is fetched in the 
order plane 4, 2, 3, and then 1, so the 
RGA bus indicates BPL4DAT ($116), 
BPL2DAT ($112), BPL3DAT ($114), 
and, finally, BPL1DAT ($110). The 
BPLNDAT values don't access regis- 
ters, but the display buffer in the Denise 
chip instead. The fetch of BPL1DAT 
triggers the serialization of all the ap- 
propriate buffers as determined by the 
bitplane setup. That's the basic idea of 
all chip bus DMA. 



THE HOST PROCESSOR 

Obviously, the Amiga chips do not 
run alone, but under the direction of a 
680x0 family microprocessor. In the 
original A1000 design, Agnus was es- 
sentially just a chip-bus master; it had nothing to do with the 
particulars of the host-bus interface. External to Agnus, a 
number of buffers and PALs controlled 680x0 access to the 
chip bus under direction of Agnus's DBR* output, which in- 
dicates when odd cycles are being used by Agnus-managed 
resources. 

Today's Agnus works very similarly, except it incorpo- 
rates these extra buffers and control functions (the "fat") on 
the chip. In this way, a 68000 processor can just about directly 
hook up to Fat Agnus. The motherboard logic need only pro- 
vide control for data bus buffer/latch circuitry, a pair of chip 
selects, and some kind of wait-state generator for the 68000 
that monitors DBR*. This logic is generally incorporated in a 
gate array, such as the Gary chip used in the A500 and A2000. 
While the modern Fat Agnus defines the chip-bus-to-host- 
bus interface in terms of the 68000 microprocessor, it's quite 
possible, via external logic, to hook it to other systems. The 
Amiga 3000, for example, defines a 32-bit chip bus and 68030 
interface for access with the addition of a bit more external 
control logic. 

Fat Agnus translates 680x0 accesses based on two chip se- 
lects. One indicates that the access is to chip RAM and caus- 
es Agnus to generate a standard RAM-access cycle. The oth- 
er chip select translates a processor address into an RGA 
address. Some RGA addresses access registers that the 680x0 
can write directly (although the OS doesn't support this use 
by user programs). In theory, any RGA value can be sent out, 
although it makes little sense in most applications to drive 
DMA channels or other dynamic RGA-bus resources. 



"Agnus was essentially 
just a chip-bus master. . . . 

Today's Agnus 

incorporates extra buffers 

and control functions 
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THE SERIAL PORT 

The serial port is one of the simplest of the custom-chip in- 
terfaces. It has no DMA-control channel, and it is accessed via 
the host processor at all times. It's mainly controlled by three 
custom-chip registers located in Paula. The SERPER (S032) 
register contains a 14-bit number representing the number of 
3.55 MHz (PAL) or 3.58 MHz (NTSC) clocks between bit tran- 
sitions, plus one. While this lets a wide range of baud rates 
be set, interrupt lag times make excessive baud rates possi- 
ble only with tight CPU read loops. The SETDATR ($018) 
register returns a single-level-buffered serial data byte, plus 
indicators for various error and buffer-state conditions. The 
SETDAT ($030) register transmits serial-data and format in- 
formation as written to it. When SET- 
DATR is full or SERDAT is empty, an 
interrupt can be generated through 
Paula's interrupt controller. 



THE CONTROLLER PORTS 

The mouse port, proportional-con- 
troller port, and light-pen port com- 
prise most of the functions available at 
the standard "controller" port of an 
Amiga system. Each unit functions via 
simple programmed I/O. The two 
mouse ports are accessed via chip reg- 
isters JOY0DAT ($0OA) and JOY1DAT 
(S00C), contained in the Denise chip. 
The two bytes of each register repre- 
sent vertical and horizontal counts of 
the mouse quadrature lines. The coun- 
ters wrap in either incremental or 
decremental directions, so it's impor- 
tant that the CPU read each register of- 
ten enough to prevent undetected wrapping. Usually once 
per vertical frame suffices for a 200DPI mouse under normal 
conditions. The mouse quadrature lines are defined to easi- 
ly permit standard digital joysticks to be read. The actual 
hardware interface to Denise multiplexes both channels into 
one set of inputs to Denise, switched on the CI* clock (3.55 
MHz or 3.58 MHz). This multiplexing rate is far more than 
sufficient to deal with mouse movement. 

The proportional-controller interface is based on a Paula- 
resident set of four registers: POTGO ($034), POTGOR 
($016), POT0DAT ($012), and POT1DAT($014). A "pot" de- 
vice is a potentiometer, which, coupled with a precision ca- 
pacitor on the Amiga motherboard, can form a time con- 
stant that is measured by Paula. A write to the POTGO 
register starts the measurement process. Both pot channels 
are grounded for approximately seven scan lines, then a 
current is applied. After each scan line, the charge on the ca- 
pacitor is compared to an internal threshold, and the ap- 
propriate POTDAT counter is incremented if the charge is 
below the threshold. As with the mouse, the 16 bits of these 
counters are divided into vertical and horizontal eight-bit 
counts. Via configuration bits in POTGO, the pot tines can 
be set up as bidirection I/O lines instead of A/D conversion 
lines. The read values in this case are returned in the POT- 
GOR register. When a mouse is used instead of a propor- 
tional controller, this mechanism is used for sensing mouse 
buttons two (right) and three (middle). A port bit in one of 
the CSG8520 chips is used to sense mouse button one (left). 
The last of the simple port interfaces is the light-pen inter- 



4 March/AprillS92 



Custom Chip Set 



^ 



~ 



~ 



the C-64 



face, which is based on Agnus registers. A light pen is de- 
signed to send a transition to the Agnus light-pen input when 
the screen pixel it is over is refreshed. That transition causes 
the state of the vertical and horizontal beam counters in Ag- 
nus to be latched in the VPOSR ($004) and VHPOSR ($006) 
registers. The vertical position, to an accuracy of one nonin- 
terlaced scan line and two low-resolution pixels, can be read 
from here. The counters are reset when the video display 
leaves the vertical-blanking interval, so it's important to read 
these during blanking for a stable result. 

THE FLOPPY-DISK PORT 

The disk interface (including control registers, DMA 
length, and DMA channel buffer/seri- 
alizer) is located in the Paula chip, with 
the DMA pointer and counter in the 
Agnus chip. The controls in Paula al- 
low for a variety of precompensation 
values in either GCR or MPM, with 4iis 
or 2us per bit cell. On reads, DMA can 
be synchronized to begin on a match 
with a value stored in the DSKSYNC 
($7E) register. Generally, all reads and 
writes are done one full track at a time; 
the disk hardware is not designed to 
deal with hardware sectors. The DMA 
capability supports large transfers with- 
out CPU intervention, and the full-track 
capability allows more logical sectors 
per track than with standard sector-ori- 
ented disk hardware. The general in- 
terrupt controller in Paula manages 
disk interrupts for "match with 
DSKSYNC" and for "DMA complete" 
conditions. 

A full disk interface requires external control lines for such 
nondata-related disk functions as unit selection, head posi- 
tioning, disk-removed sensing, and the various other ele- 
ments of an industry-standard floppy-disk interface. These 
are handled by CSG8520 chips in Amiga systems. An index 
interrupt is also provided by way of a CSG8520 interface. 

THE AUDIO SUBSYSTEM 

Paula and Agnus house a considerable number of control 
registers that are associated with each of the four Amiga 
sound channels. Each sound channel has an Agnus-resident 
DMA-control unit to drive it from a sound-data table stored 
in memory. Sound data for any channel is a series of signed 
eight-bit values. The length of the sound table is also con- 
sidered by the DMA controller, so the counter may auto- 
matically reset after playing through a sample, allowing a 
continuous sound to be played by each of the four channels 
with absolutely no processor intervention after setup. This al- 
lows the Amiga system to work as easily as computers with 
unattended "sound-chip" audio, as found in the C-64, with- 
out sacrificing the more flexible D/A sound-generation 
scheme that often requires constant CPU update on other 
systems. 

Control registers allow a variety of options to be set for au- 
dio generation, and each basic parameter is available inde- 
pendently for each of the four channels. For volume control, 
a six-bit attenuation value (from to -36.1dB) can be set. The 
frequency is expressed as a period based on the number of 
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video clocks between samples. As shown in Figure 2, each 
channel gets one DMA cycle per scan line, which fetches two 
sample values. This sets a lower limit on the period of the 
sample of 34.642jis, which is equivalent to a maximum sam- 
pling rate of 28.867 KHz. This rate defines a Nyquest fre- 
quency of 14.334 KHz, about the frequency response of a de- 
cent cassette deck using CR02 tape (however, with only 
eight-bit samples, it won't have the dynamic range of cas- 
sette). Other registers permit channels to modulate each oth- 
er in period and volume. As usual, the register address used 
by the audio DMA channels can be driven directly by the host 
CPU. The CPU can, of course, drive the audio-output chan- 
nels at higher frequencies, because it's not limited to two 
samples per scan line. In addition, it 
can modulate the volume control for 
extended dynamic range, as the CPU to 
chip-bus bandwidth permits. 



PLAYFIELDS AND THE COPPER 

Display playfield management and 
the Copper are both located in Agnus. 
As discussed earlier, a main function 
of the Copper is to load chip registers, 
such as the bitplane pointers. As well 
as loading, the Copper unit receives in- 
put from the vertical- and horizontal- 
line counters (also in Agnus), which al- 
low the Copper to wait for any 
particular position in a display. The in- 
teraction of WAIT and MOVE instruc- 
tions is responsible for the sliding- 
screen feature you see under Intuition. 
Each change of screen involves a Cop- 
per wait, followed by a series of Cop- 
per moves to change display mode, color-table entries, and 
bitplane pointers. The space between screens is actually the 
result of the time it takes for all these Copper moves to run. 
The CPU is only involved when the user is moving the 
screens. 

The main use of the Copper is in setting up bitplanes for 
display. Once these are set up, Agnus is responsible for gen- 
erating bitplane-fetch cycles on the RGA bus, while Denise 
takes the fetched data, indexes it through the Color Lookup 
Table (CLUT), and ultimately generates 12 bits of digital- 
video output. The display hardware is extremely flexible. 
Registers in Agnus and Denise set up the size of a screen's 
pixels (139.68ns, 69.84ns, or 34.92ns), the horizontal and ver- 
tical size of the actual display, the bitplane line modulo for 
Agnus's display DMA counters, and such special modes as 
interlace, HAM, dual-playfields, and so on. When properly 
set up, Agnus generates the aforementioned DMA plane- 
fetch cycles (RGA address in the BPLNDAT range). 

When Denise responds to a bitplane DMA cycle, it buffers 
up one word from each plane until there are enough to sup- 
port the selected display mode. The pixel serializer routes 
pixels through special priority logic, which considers dual- 
playfields and sprites, and then to the CLUT, one pixel at a 
time. An interesting feature of the current Denise is that 
CLUT entries actually run at low-resolution pixel speed, 
139.68ns. If the pixels are going at double speed ("high reso- 
lution"), the pixel stream input to the CLUT is actually multi- 
plexed, so that every other pixel is from equally configured 
opposite halves of the CLUT. For ECS quad-speed pixels i 
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("SuperHires"), pixel data is actually multiplexed after the 
CLUT. This accounts for the reduced number of SuperHires 
colors (64 rather than 4096) and the rather weird CLUT con- 
figuration the mode requires. 

THE SPRITE HARDWARE 

Sprites are small graphic objects controlled independently 
of the main display playfields. The system hardware sup- 
ports eight sprites, each of which has its own Agnus-con- 
trolled DMA channel that fetches data in the scan line im- 
mediately before the main display fetch begins. Each sprite 
can be up to 16 139.68ns-pixels wide and two bitplanes deep. 
This is based on the sprite DMA channel, which fetches 32 
bits per sprite per scan line. Because 
there is a sprite fetch on every scan line, 
sprites can be any number of pixels 
high. 

Sprite bitplanes don't work exactly 
like display bitplanes. They're orga- 
nized in memory so that only one 
sprite-data pointer is required for each 
sprite; the two WORDs for each scan 
line are consecutive in memory. Like 
bitplane pointers, sprite pointers are in- 
cremented as the sprite is serialized, so 
they need to be updated by the Copper 
at the start of every display. Also, only 
three of the possible combinations of 
sprite-pixel data access color registers; 
the fourth value always indicates trans- 
parency. Agnus also contains registers 
for sprite position and control. These 
are actually written by the sprite DMA 
channel before any sprite display oc- 
curs, greatly simplifying the software necessary for sprite 
management. The position and control registers set the hor- 
izontal start position, vertical start, and vertical stop position 
of each sprite. These values are compared with the value of 
the vertical and horizontal display counters, and the sprite 
engine starts sprite pixel generation when a comparator trig- 
gers it. CPU control of the sprite registers can allow the reuse 
of sprites on the display, in return for some 680x0 cycles 
spent. 

The control register also permits a feature called attached 
sprites: The pixel data from two sprites is taken together to 
form a four-bit CLUT entry, allowing what appears to be one 
sprite supporting 15 colors and transparency. Attached 
sprites can move independently and only get taken together 
when they overlap. If they aren't attached, overlapped sprites 
normally overlay each other on the display, with sprite in 
the front and sprite 7 at the back. Sprite overlay priorities are 
fixed, but a register in Denise supports rather flexible control 
of how the sprites interact with either of the two possible 
playfields, allowing sprite groups to sit in front, behind, or 
between the playfields. 

THE BLITTER 

Perhaps the most heralded feature in the Amiga chips is 
the Bit Image Manipulator or Blitter (called the "bimmer" 
by the original Amiga designers). This device, which occu- 
pies a substantial portion of the Agnus chip register and log- 
ic space, supports high-speed logical operations and moves 
on graphic images. The idea is that, with such hardware 
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specifically designed for bit image manipulation, a basic 
68000 system can stay low cost and still boast display per- 
formance characteristics of machines with several times 
more CPU power. 

Agnus supports four DMA channels for Blitter data ac- 
cess, three for source operands (channels A-C), and one for 
destination (channel D). To support each channel, Agnus pro- 
vides a separate pointer, pointer modulo register, and chan- 
nel-enable bit. Additionally, channels A and B have barrel 
shifters, to perform bit-alignments without overhead. A com- 
mon set of registers define the rectangular size of an opera- 
tion, and the operation that will be performed. Any binary 
operation among the A, B, and C channels can be generated, 
with output to the D channel. Opera- 
tions can include disabled channels that 
then act as constants with no DMA cy- 
cle. Additionally, Agnus pipelines the 
Blitter operation such that one Blitter 
read or write can take place every chip- 
bus cycle, as long as there are open slots 
on the chip bus to support this. 

A few Agnus control registers allow 
modifications to the basic Blitter oper- 
ation. To support blits of overlapping 
regions, the blit can be done with in- 
crement or decrement of the channel 
pointers and modulo. To handle end- 
point conditions on shifted blits, a pair 
of registers can supply end-point masks 
for the A channel. There are also a va- 
riety of area-fill modes in which the 
Blitter automatically fills the area on the 
selected sides of a series of single-pixel 
lines, with carry to support filling over 
multiple blits. There is also a special line-drawing mode that 
allows a patterned line to be drawn very quickly. The oper- 
ation register is still active in this mode, so a number of dif- 
ferent line operations are possible. 

Considering that the maximum size of a blit is 1024x1024 
pixels in the original Agnus (32Kx32K in ECS Agnus), you 
should expect any given Blitter operation to take a relatively 
long time. To support parallel operation of the Blitter and 
host processor, the interrupt controller in Paula supports a 
relatively low priority "Blitter done" interrupt. 

MORE TO EXPLORE 

We've just scratched the surface of the Amiga chip sub- 
system. For more information on the register-level details of 
the Amiga chips, I recommend the Amiga Hardware Reference 
Manual, from Addison-Wesley. At over 350 pages, it still 
doesn't thoroughly cover every detail of the custom chip set. 

In terms of resolution or number of colors, the Amiga chips 
may no longer be the hottest thing on the market, but they 
are still among the most sophisticated support chips used in 
any microcomputer. The basic architecture continues to hold 
up and shows promise for the future as well. ■ 

Dave Haynie was a senior engineer on the Amiga 2000, Amiga 
2500, and Amiga 3000 computers and was the architect of the Zor- 
ro III expansion bus. He continues to be a driving force in Amiga 
system architecture and high-end design. Contact him c/o The 
AmigaWorld Tech Journal, SO Elm St., Peterborough, NH 
03458, or on BIX (hazy). 
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Easy File and Font Requesters 

Try 2.0's ASL library (and our 1.3 alternatives) 
for ready-made interface help. 

By Willy Langeveld 



IN A MOVE towards standardization of interfaces, version 
2.0 of the operating system provides a set of versatile file and 
font requesters via its ASL library. As you will see, you can eas- 
ily tailor these requesters to fit the needs of most applications. 

THE ASL LIBRARY 

The ASL library contains three main functions. AllocAsl- 
RequestQ and FreeAslRequestO respectively allocate and free 
an ASL file or font requester. Once a requester is allocated, 
AslRequest() displays it and allows the user to choose a file 
or font. The library's three additional functions — AllocFile- 
RequestQ, FreeFileRequestf), and RequestFile() — are provid- 
ed only for backward compatibility with early versions of 
AmigaDOS 2.0x. As they were supplanted by particular in- 
vocations of the more general ...Asl... calls, Commodore 
discourages their use. The examples that follow use the three 
. . . Asl . . . functions only. 

The link library Amiga. lib (or the equivalent thereof for 
other C compilers) contains two other functions that interface 
to asl.library's offerings — AllocAslRequestTagsQ and AslRe- 
questTagsQ. These differ from their nontags counterparts be- 
cause they take a variable number of tag items as arguments, 
rather than a pointer to an array of tag items. Note, howev- 
er, that you cannot use these functions if you link your pro- 
gram with cres.o under SAS/C, because they make absolute 
references to AslBase and IntuitionBase (as do other functions 
in Amiga. lib). In the Langeveld drawer of the accompanying 
disk, Example! uses AllocAslRequest() and Example2 uses 
AllocAslRequestTags(). 

Before you plunge into coding, take note that asl. library re- 
sides in the Workbench 2.0x libs: directory, not in ROM. 
Therefore, the user might delete asl. library from his floppy 
to make more room; your application must be able to handle 
the possibility that it cannot open the library. 

THE BASIC PROCEDURE 

The basic procedure to bring up an ASL requester is to ini- 
tialize an array of Tagltems, allocate the type of requester 
you desire, display the requester, extract the needed infor- 
mation, and free the allocated resources. Consider the code 
required for a file requester (for a font requester simply sub- 
stitute "font" for "file" when appropriate): 

(•include <librarles/asi.h> 

struct FiicRequester 'freq; 

/* 

* Substitute for N the number of tag Items: 



*/ 

struct Tagltem tags[N+1); 

BOOL result; 

f 

* Initialize tags array 
"/ 

tags[ ].ti_Tag = ASL_...; 
tags[ ].ti_Data = (ULONG) ...; 

tags[N-1].ti_Tag = ASL_...; 

tags[N-1J.ti_Data = (ULONG) ...; 

tags[ N J.tLTag = TAG_END; 

f 

' Allocate the file requester 

7 

freq = (struct FileRequester *) 

Alloc As!Request(ASL FileRequest, tags); 
f 

* Put up the requester 
*/ 

result = Aslflequest(freq, NULL); 
/' 

* Extract Info from freq 
*/ 

If (result) { 

} 

I' 

' Free the requester and all associated 

' resources. 

V 

FreeAslRequest(freq); 

As you can see, AllocAslRequest()'s arguments are a re- 
quester type and an array of tags. If you hand a NULL point- 
er to Alloc AslRequestQ instead of a tags array, you have a 
reasonable default file requester. The tag items merely over- 
ride the defaults. AllocAslRequestQ returns a pointer to a file 
requester or NULL, if it ran out of memory or failed for an- 
other reason. 

Both AslRequest{) and FreeAslRequestQ take the pointer 
AllocAslRequest() returns as their first argument. AslRe- 
quest() also accepts another array of tag items as a second ar- 
gument. This arrangement allows you to set up a file re- 
quester structure once using AllocAslRequest() and to modify 
only a few parameters in subsequent calls to AslRequestQ. 
Also, all settings the user changes (such as the position and 
size of the requester) are retained if the same requester struc- i 
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ture is used. I highly recommend this mode of operation. 
(Because the examples on disk use each requester only once, 
however, they do not take advantage of this feature.) 

Note that AslRequestQ returns a BOOL to indicate if the 
user selected a filename (TRUE) or cancelled the request 
(FALSE). Early documentation listed this function as return- 
ing a pointer to the filename the user selected, which is in- 
correct. The early versions of this function returned the file- 
name, but without the associated path. 

Clearly, 1 glossed over the most interesting parts of the 
process: how to initialize the tags array and how to get in- 
formation back from the requester after the user has made a 
selection. Let's examine the tags issues first. 

TAG ITEMS 

Basically, a tag item is a pair of numbers — a tag and a val- 
ue. The Tagltem structure is: 

struct Tag Item { 
Tag ti_Tag; 
ULONG ti_Data; 

}; 

where Tag is defined to a ULONG via a typedef statement. 
The ti_Tag field specifies the type of data represented by the 
tag item, and the ti_Data field contains or points to the data. 
(For more on tags, see "Tag Tips," p. 8, November/Decem- 
ber '91. ) The basic functions in the ASL library take an array 
of Tagltem structures as a parameter. Each tag item describes 
a particular modification to the requester's default charac- 
teristics that are displayed. For example, to change the x lo- 
cation of the requester, which by default might come up in 
the top-left corner of the screen, you would include a tag 
item such as: 

tags[4].ti Tag = ASL_LeflEdge; 
tags[4].ti_Data = (ULONG) 100; 

as part of the tags array in the code. The location in the array 
(in this case, 4) is unimportant. 

All ASL parameters, structures, and tags are defined in the 
include file libraries/asl.h. The tags and a short description 
of the data they require follow. 

Tags valid for both kinds of requesters: 



Tags valid for the file requester: 



Tag 

ASL.LeftEdge 

ASL_TopEdge 

ASL_Hail 

ASL OtCText 

ASL_CancelText 



ASL Window 



ASL FuncFiags 
ASL_HookFun 



Data 

Position of the requester's left edge. 
Position of the top edge. 
Pointer to a string of text for the title bar. 
Pointer to text for the Okay gadget. 
Pointer to text for the Cancel gadget. Both the 
Okay and Cancel gadgets can display a maximum 
text size of six characters. 
Pointer to the parent window: The requester 
shares the IDCMP of this window unless instructed 
otherwise. Also, the screen to open on is deter- 
mined by finding the screen the parent window 
is on. 

Bit mask with various flags, see later. 
Pointer to a call-back function. The ASL requesters 
can be instructed to call this function for each font 
or file to let the function determine whether the 
font or file in question should be displayed. The 
ASL requesters can also be instructed to call this 
function in case of IDCMP activity in the parent 
window. 



Tag 

ASL_Wldth 
ASL_Height 
ASL_Flle 

ASL.Dir 
ASL_Pattern 



ASL_ExtFlags1 



Data 

Desired width of the requester. 

Desired height. 

Pointer to a default filename. This filename is 

initially displayed In the requester's File gadget. 

Pointer to the Initial, default, pathname. 

Pointer to a default pattern string. All files (and, 

if requested, directories) are checked and dis 

played only if they match the pattern. 

Bit mask with more flags, see later. 



Tags specific to the font requester: 



Tag 
ASL_FontName 

ASL„FontHeight 
ASL FontStyles 

ASL_FontFlags 
ASL_FrontPen 

ASL BackPen 
ASL_MlnHeight 

ASL Max Height 

ASL_ModeLlst 



Data 

Pointer to default font's name. This font is Initial- 
ly displayed in the requester. 
Default font height. 

Default font styles, see gfx.library's TextAttr 
structure for more details. 
Default font flags, see the TextAttr structure. 
Default pen number for the "front" color, the 
color in which the font's characters are drawn. 
Default pen number for the background color. 
Minimum font height. Fonts shorter than this will 
not be displayed. 

Maximum font height. Fonts taller than this will 
not be displayed. 

Pointer to an array of strings to use for the 
drawing mode cycle gadget. This allows you 
to replace the entire cycle gadget including its 
label (Mode:). By default, the cycle gadget con- 
tains the mode JAM1, JAM2, and Complement. 
The first pointer should contain a pointer to a 
new label for the gadget. The last pointer should 
be set to NULL to indicate the end of the array. 

Note: The width and height of the font requester cannot be 
specified. If the corresponding tag items are present, they are 
ignored. 

FUNCTION FLAGS 

You can also set flags using the ASL_FuncFlags tag item. 
For the file requester, your choices are: 

Flag Requester Action/Attribute If Flag Is Set 

FILF_DOMSGFUNC Calls the call-back function specified via 

ASL_HookFunc, with all the IDCMP messages 
that arrive at the parent window'suserPort. 

FILF DOWILDFUNC Calls the call-back function for each file to check 
if the file is to be included in the display. 

FILF_MULTISELECT Allows multiple files in the same directory to be 
selected. 

Uses its own IDCMP port; does not share parent 
window's. 

Contains a pattern gadget. 
Changes the highlight state of the scrolling dis- 
play, has the following properties: is not multi- 
ple-select, can create directories that are entered 
by the user and do not yet exist, does not sup- 
port double-clicking on file names to prevent 
accidental overwriting of existing files. Use this 
flag for "Save" requesters. 



FILFJJEWIDCMP 

FILF_PATGAD 
FILF SAVE 
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For the font requester, the following flags apply: 



Flag 
FONF_FRONTCOLOR 



~ 



FONF_BACKCOLOR 
FONF„STYLES 

FONF DRAWMODE 

FONF_FIXEDWIDTH 
FONF_NEWIDCMP 

FONF_DOMSGFUNC 
FONF_DOWILDFUNC 



Requester Action/Attribute If Set 
Has a gadget to select the "front" color (color 
the text Is drawn in). 

Has a gadget to select the background color. 
Has check boxes to select combinations of 
display styles (boldface, Italics, underlined). 
Has a cycle gadget for drawing modes (de- 
fault JAM1, JAM 2, and Complement). 
Displays only tixed-wldth fonts. 
Uses its own IDCMP port; does not share the 
parent window's. 

Calls the call-back function specified in the 
ASLHookFunc tag item, with all parent 
window IDCMP messages. 
Calls the call-back function to inquire 
whether to include or exclude a font from 
display. 

The file requester also has a couple of flags that you can set 
in the ASL_ExtFlagsl tag item: 

Flag Requester Action/Attribute If Set 

FIL1F NOFILES Is a directory requester. No files are displayed, 

no File gadget Included. 
FIL1F_MATCHDIRS Checks directory names during partem matching. 

I'll discuss individual flags in more detail as we encounter 
them in the examples. 

THE FILE- AND FONTREQUESTER STRUCTURES 

The structure returned by AllocAslRequestQ is either a 
struct FileRequester or a struct FontRequester depending on 
the type asked for. The public fields in the file requester struc- 
ture are: 

struct FileRequester { 

BYTE *rf File; 
BYTE *rLDIr; 

WORD rf_LeftEdge, rLTopEdge; 
WORD rf_Width, rf„Height; 

LONG rf_NumArgs; 
struct WBArg "rf_ArgList; 
APTR rf_UserData; 



nonconforming file- or pathname anyway. 

The next four fields contain the position and size of the re- 
quester as it was just before the user closed it. As a matter of 
user-interface style, it may be desirable to remember these 
values and use the corresponding tag items to initialize the 
next invocation of the same requester to the same numbers. 
If you use the same requester structure in subsequent calls to 
AslRequestQ, this is automatic. 

For a multiple-select file requester, the files are returned as 
a WBArg list — the same kind of argument list that is present 
in the WBStartup message sent to applications when they are 
started from the Workbench. The number of files in this list is 
stored in the rf_NumArgs field and the names of the files and 
locks on their home directories are returned in the array of 
WBArg structures to which the rf_ArgList field points. Note 
that only the filenames themselves are in this list. You can ei- 
ther concatenate the names with the contents of the rf_Dir 
field to get complete (relative) pathnames, or you can use the 
lock in the WBArg structure to find the file and use Name- 
FromLockQ to obtain the full pathname. The latter method is 
preferred (more on this in the Example2 discussion). 

You can write to the rf_UserData field — an exception to 
the rule. Typically this is useful for nonblocking requesters 
where tbe application needs to keep track of the context from 
which the requester was called. Example2 uses this field to 
pass the parent window pointer to the call-back function in 
a reentrant way. This field needs to be initialized before the 
call to AslRequestQ. 

Finally, the rf_Pat field contains the last pattern that was 
present in the Pattern gadget, if such a gadget was displayed. 
You can instruct the file requester to list only files matching 
a certain pattern in two ways: by specifying the pattern either 
as part of the ASL_Dir tag item or separately with an ASL_ 
Pattern tag item. The pattern in the ASL_Dir tag item will not 
be displayed anywhere, even if there is a Pattern gadget. Yet, 
only files matching the pattern will be shown. If an ASL_Pat- 
tern tag item is specified, the requester will show only the 
files that match that pattern, and if there is a Pattern gadget, 
that pattern will be shown in it. If both pattern-matching 
methods are used together, then all files displayed match 
both patterns. Note that you can use the ASL_Pattern tag 
item without a Pattern gadget, but, the user cannot change 
the pattern in this case. 

For the font requester structure, the public fields are: 

struct FontRequester { 



~ 



BYTE *rf_Pat; 

}; 

With one exception, these fields should not be written to by 
the application — they are of interest only after the AslRe- 
questQ function has returned. For a single-select file requester, 
the filename is returned in the rf_File field and the path (if any) 
in the rf_Dir field. The path returned is precisely what was last 
displayed in the Drawer gadget in the requester, so it may be 
a full path specification, a relative path, or nothing at all if the 
file is in the "current" directory. Similarly, the filename is 
what last appeared in the File gadget. Note that this means 
that any restrictions that were in effect during the display of 
the requester (whether in the form of a pre-supplied wildcard 
pattern or imposed by the call-back function) need to be 
checked again by the application: The user may have typed a 



struct TextAttr fo_Attr; 
UBYTE fo_FrontPen; 
UBYTE fo^BackPen; 
UBYTE fo_DrawMode; 
APTR fo. UserData; 

}; 

The fo_Attr field is a complete TextAttr structure that con- 
tains the values for the selected font. You can clone it and use 
it directly in a call to OpenFontQ or OpenDiskFontQ. Specif- 
ically, the name of the selected font is in the ta_Name field of 
this TextAttr structure. The other fields in the FontRequester 
structure contain the front pen, back pen, and drawing mode 
selected by the user, respectively. The front and back pens are 
returned as pen numbers and the drawing mode is returned 
as for JAM1, 1 for JAM2, and 2 for COMPLEMENT mode 
(see graphics /rastporth), unless you substitute your own 
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list. If you do, the sequence number of the item In the list is 
returned, with the first item in the list. 

Again, these fields are read-only by the application, with the 
exception of the fo_UserData field, which you can write to as 
in the case of the file requester, 

ASL IN ACTION: EXAMPLES ON DISK 

The Langeveld drawer of the companion disk contains: 

Examplel The first example program. 

Example2 The second example program. 

Example!. c The main routine and Initialization for the first example. 

Example2.c The main routine and Initialization for the second 

example. 

makefile The dependencies file for the two programs. 

MyARP.h An abbreviated ARP include file. 

requesters'!. c The ASL and ARP requester Interfaces for Example!. 

requesters2.c The ASL requester interfaces for Example?, 

simpreq.c A simple string requester, 

util.c A variety of utility functions used In the examples. 

All C files are compiled using SAS C with 16-bit ints (-w 
option). This is to ensure that the examples will run that way, 
not because if is necessary or even desir- 
able. It does point out, however, the need 
to cast tag item values to ULONG in var- 
ious places, so this is a useful exercise. 

Examplel provides basic examples of 
typical file, directory, and font re- 
questers, including all the code you need 
for a "complete" user interface and to 
handle the problems you might en- 
counter under AmigaDOS 1.3 and 2.0. 
Under 2.0, the program uses the ASL re- 
questers, while under 1.3 it brings up the 
file requester available in the ARP li- 
brary. If neither is present, Examplel 
falls back to a simple string requester. It 
is written in a modular fashion, so you 
can compile requestersl.c, utile, and 
simpreq.c and link the object modules 
to your application with a minimum of work. The function 
calls are very simple and take care of all the details, includ- 
ing frequently omitted style issues such as blocking user-in- 
put in the parent window and displaying a busy pointer if the 
parent window is activated. In addition to handling the dif- 
ferent OS versions transparently, Examplel makes sure that 
DOS requesters and the requesters themselves come up on a 
visible part of the proper screen. 

When you run Examplel from the Shell, you see a usage 
note and the first requester. The usage note explains that the 
program takes up to four command-line arguments: window, 
screen, usearp, and noarp. When no arguments are specified, 
the program cycles through the three requesters and indicates 
whether something was selected and if so, what. 

If the window argument is specified, a "parent" window 
will open before the first requester. This window can be re- 
sized and has both a close button and a regular Intuition gad- 
get. When the first requester appears and you click in the par- 
ent window, the mouse pointer becomes the standard Amiga 
busy pointer. When you try clicking on the gadget in the par- 
ent window, nothing happens — all Intuition input to that 
window is blocked. Clicking on the Close gadget will not re- 
sult in a message sent to that window, although resizing the 



"Under 2.0, the program 
uses the ASL requesters, 
. . . under 1.3 it brings up 
the file requester available 
in the ARP library," 



window prompts a NBWSIZE message when the requester 
closes. The requesters in this example are "blocking"re- 
questers that comply with the Amiga User Interface Style Guide's 
(Addison- Wesley) recommendations for "modal" requesters. 
If the screen argument is also present, a new screen is 
opened first. The window and its associated requesters then 
open on this screen and everything works as before. Note, 
that if the screen argument is present but the window argu- 
ment is not, the requesters open on the Workbench and the 
screen covers everything. It is not possible to open ASL re- 
questers on screens if they do not have a parent window, 
with the exception of the current default public screen. With 
the ARP requester this is possible, because the ARP requester 
can be set to call a call-back function with the requester's 
NewWindow structure. (I use this feature of ARP in Exam- 
plel, but only to set the requester position, not to make it 
open on the screen). 

If the usearp argument is present, the example "simulates" 
the absence of asl.library. In this case, the program displays 
a system requester allowing the user to cancel, retry, or go on 
anyway. This provides an example of using the new EasyRe- 
quest() function (which is not part of asl.library). Of course, 
this will only happen under AmigaDOS 
2.0x. A retry causes the program to con- 
tinue as if the user copied asl.library back 
to his libs: directory. When "Go On Any- 
way" is selected, the program uses a 
combination of the ARP file requester 
and the simple string requester. 

Finally, when noarp is specified in ad- 
dition to usearp, the program simulates 
the absence of both libraries and only 
simple string requesters are used. 



DISSECT THE SOURCE 

Looking at Examplel.c, you'll find a 
number of includes and then the proto- 
types for the three main functions in re- 
questers!. c: GetFileNameQ, GetDir- 
Name(), and GetFontNameQ. The main 
program begins by calling the function IntroQ, which parses 
the command line arguments and returns a set of flags. Ln- 
tro() also prints out the usage message. The flags are used to 
call the function OpenStuffQ. 

OpenStuffQ deserves a few remarks. The part of interest is: 

... AslBase - OpenLibrary("asl. library", OL); 
If (AslBase = NULL) { 

if (lntult!onBase->LibNode.llb_Verslon >= 36) { 
while (AslBase == NULL) { 

reply = EasyRequest(NULL, &CheckForAsl, NULL, NULL); 

if (reply == 0) goto cleanup; 
if (reply == 2) break; 

AslBase = OpenLibrary("asl.library", OL); 
} 
J 
If (AslBase == NULL) { 
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If the ASL library cannot be opened, OpenStuffQ checks if 
it's running in 2.0 (Intuition's version is 36 or larger). If it is, 
it opens a system requester via EasyRequest() to ask the user 
what to do. The EasyRequest{) structure, CheckFor Asl, is ini- 
tialized at the top of the function. The requester has three but- 
tons; if the user clicks on Cancel (reply is 0) the program 
quits, if the user clicks on Go On Anyway (reply is 2), it 
breaks out of the loop without opening ASL, and if the user 
clicks on Retry, Examplel tries opening the ASL library again. 

Next OpenStuffQ opens a screen that has the 2.0 3-D look: 

if {Hags & SCREEN) { 

if (AslBase) { 

testscreen = OpenScreenTags(NULL, 

SA Depth, (ULONG) 3, 

SA_Pens, (ULONG) penarray, 

SA_Title, (ULONG) "ReqTest", 

SAJJisplaylD, (ULONG) HIRES I LACE, 

TAG_END),- 
} 

else{ 

testscreen = OpenScreen(&ns); 
} 

1 

The trick here is to useOpenScreenTagsQ with the SA_Pens 
tag item included. The penarray was declared earlier in the 
file to be the minimal form acceptable for this purpose: 

static UWORD penarray = {OxFFFF}; 

Under AmigaDOS 1 .3, OpenStuff() opens a screen using 
OpenScreenQ and a NewScreen structure. 

Other functions in this file are CloseStuff() and ChecklD- 
CMP(). The former closes all the opened resources, and the 
latter checks whether any messages arrived on the parent 
window's IDCMP. 

Back to the main function: It contains three "exercises." 
The first calls GetFileName(), whose arguments are pointers 
to the parent window, a filename buffer, a pattern, and a 
"hail" string. The filename buffer may be initialized to a de- 
fault value, in this case foo.foo. If the user cancelled the re- 
quester, GetFileNameQ returns FALSE, and a descriptive 
message is printed. Note that in this case the default filename 
is not overwritten. If the user selected a file, that filename is 
displayed. PostMsgQ prints to the parent window if one was 
opened, otherwise it prints to the Shell from which the ex- 
ample was launched. After the exercise, the program checks 
the parent window's IDCMP to see if messages arrived. Sim- 
ilarly, the second exercise brings up a directory requester by 
calling GetDirNameQ, and the third displays a font requester 
by calling GetFontNameQ. Let's take a closer look at how 
these functions work. 

REQUESTERSl.C 

The first thing you notice in requestersl.c is that GetFile- 
NameQ is just a wrapper for calls to routines specific to the 
ASL, ARP, or simple string requesters. Next are calls to the 
functions Set/ClrWindowBusy() and SetTaskWindowQ, 
which are described in more detail later. SetWindowBusyQ 
sets a busy pointer for the parent window and blocks out In- 
tuition activity. SetTaskWindowQ causes DOS requesters to 
appear on the proper screen while the file requester is up or, 



alternatively, causes them to not appear, if it is called with an 
argument of -1. At the end of GetFileNamef), both changes 
are undone. The ASL requesters themselves do not take care 
of these details for you. 

The function GetFtleNameASL() starts by copying the file 
and path parts of the default filename into buffers called fil 
and dir. These buffers have a fixed size of 256 bytes — Ami- 
gaDOS is still limited to pathnames that are 255 characters or 
fewer. (While AmigaDOS can support directory nestings 
whose full path specification is larger than 255 characters, no 
single path specification can be longer.) The splitting is done 
using the new AmigaDOS functions FilePartQ and PathPartQ, 
which each take a complete filename as an argument. They 
behave almost identically, the only difference being that 
FilePartQ returns a pointer to the beginning of the filename 
part of the string, whereas PathPartQ returns a pointer to the 
: or / just before the filename, if either exists. 

AddPartQ adds the pattern specification, given in the third 
argument of GetFileNameASL(), to the path part. The re- 
quester the program brings up does not have a pattern gad- 
get, but lists only files matching the pattern. Note, that the 
pattern is not displayed anywhere in the file requester. 

This example tries to open the requester at an x, y location 
of 150, 50. If the user has previously dragged the screen al- 
most all the way down, however, the requester normally 
would be invisible. If there is a parent window (as in most 
applications), then the functions find_bestx() and find_besty() 
try to compensate for the position of the screen and modify 
the suggested values they take as their second argument. 
Note that this is of great importance with large overscanned 
screens or the 2.0 AutoScroll screens. Ideally speaking, the re- 
questers should appear more or less inside the outer borders 
of their parent window. The fmd_bestx/y() functions don't 
currently do this, but could be enhanced with a bit of work. 

Finally, the tags array is initialized and the requester is al- 
located and displayed using the basic procedure described 
earlier. Notice that the flag FILF_NEWIDCMP is specified, 
making this a blocking requester. After the requester returns, 
the path- and filenames are extracted and combined into a 
single filename, if the user actually made a selection (result 
being TRUE in that case). 

GetFileNameARPQ cannot use the various ...PartQ func- 
tions, because it is presumably running under AmigaDOS 1.3. 
The \KV library docs contain lunelions that do similar things, 
but in these examples I wanted to concentrate on ASL and to 
minimize the number of ARP functions used. Roughly equiv- 
alent code separates the file and path parts and adds them to- 
gether again. 

The function GetDirNameQ is very similar to a merged 
version of GetFileNameQ and GetFileNameASLQ. The im- 
portant difference is that the ASL_File tag item is missing 
and that an ASL_ExtFlagsl item is added: It sets the FIL1F_ 
NOFILES flag, making this a directory requester. It looks con- 
siderably simpler, mainly because no temporary buffers are 
needed and no paths and files need to be assembled or dis- 
assembled. There are currently a few bugs in this form of the 
requester. The Path gadget does not automatically get acti- 
vated, and when a name is typed in the gadget and the user 
presses return, the requester does not close: The user must 
click the Okay gadget or use the equivalent menu item. These 
problems are likely to be fixed in the future. 

Finally, we have the function GetFontNameQ. For demon- 
stration purposes, this font requester lists only fixed-width ► 
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fonts that come in at least two sizes: eight pixels wide by 
eight pixels tall and eight pixels by 11 pixels. The tag items 
ASL_MinHeight and ASL_MaxHeight, plus the FONF_ 
FIXEDWIDTH flag in the ASL_FuncFlags tag item specify 
part of this, the rest has to be done with a call-back function. 
This function, FontHookQ, is specified in the ASL_HookFunc 
tag item and announced in the ASL_FuncFlags tag item us- 
ing the FONF_DOWILDFUNC flag. After the requester re- 
turns, the program finds the font name in the TextAttr struc- 
ture contained in the FontRequester structure. 

FontHook() is called by the font requester with three ar- 
guments: the type of the call (the reason the function was 
called), a pointer to an object, and a pointer to the file re- 
quester structure itself. In case the type is FONF_DOWILD- 
FUNC, the object is a TextAttr structure. Because the TextAttr 
structure doesn't contain sufficient in- 
formation for the requirements of the ex- 
ample, it calls CheckFont(), which opens 
both the desired fonts based on the font 
name and checks that they satisfy the 
conditions. CheckFont() is in util.c. 



The Process structure 



UTIL.C 

The function SetWindowBusyQ sets 
the 2.0 or 1.3 AmigaDOS busy pointer 
for the parent window of the requester. 
It also puts up a "real" (Intuition) re- 
quester in that window. That requester 
has, however, no size (0 pixels wide and 
tall), so it is completely invisible. It does 
have the effect of completely blocking all 
IDCMP traffic to that window. If an ap- 
plication must have a blocking requester 
that is really a window (as is the case with the ASL re- 
questers), the Amiga User Interface Style Guide recommends 
the actions performed in this function. ClrWindowBusyQ un- 
does the actions of SetWindowBusy(). Respectable sources 
have recommended using a 1-pixel-wide and -tall requester 
located relative to the window at position (-1, -1), but this 
overwrites random memory in some cases and should, there- 
fore, not be used. 

Next, CheckFont() calls GetFont(). This function attempts 
to open a font when given a TextAttr structure and a width 
and returns a pointer to the font. CheckFontQ itself tries to 
obtain 11x8 and 8x8 versions of a font and returns failure if 
either or both don't exist. 

The functions find_bestx() and find_besty() determine the 
location of the left and top edges of the screen (Viewport, ac- 
tually) the window is currently on. If the screen is not in the 
normal position, the functions try to compensate by return- 
ing adjusted values for the requester position. 

SetTaskWindow() solves a problem with DOS requesters. 
The Process structure of each process on the Amiga contains 
a default-window pointer that is normally set to NULL. With 
this pointer AmigaDOS determines where to place its own re- 
questers (such as "Insert volume foo: in any drive"). Most of- 
ten, these appear on the Workbench, even if the application 
has a screen of its own. When an application does something 
that might prompt such a requester, it should set the process- 
window pointer to the main window on its screen. The DOS 
requesters will then appear on this screen. Notice also that the 
process window must at all times be a valid window point- 
er or else when a DOS requester needs to open, the system 



of each process on the 
Amiga contains a default- 
window pointer that is 
normally set to NULL. " 



will crash. For this reason, always restore the process-win- 
dow pointer to the original value as soon as possible. Set- 
TaskWindow() sets the process-window pointer to the one 
given as its argument and returns the previous value of the 
process-window pointer. A second call to SetTaskWindow() 
with this old window pointer restores the original value. 
When the process-window pointer is set to -1, DOS re- 
questers are not displayed. For demonstration purposes, I 
set the process-window pointer to -1 if there is no parent 
window and to the parent window if there is one. 

The next functions, AddListQ and NukeListQ, are used 
only in Example!. AddListQ adds a node to an already ex- 
isting Exec list with the node name set to a copy of the string 
passed as a second argument. If the list doesn't exist yet, a 
new list is created. The function returns a pointer to the list 
or NULL if it ran out of memory. Nuke- 
ListQ takes a list allocated by AddListQ 
and deallocates it. 

The last two functions in util.c are a 
case-insensitive compare called strcmpu 
and a rindex function that behaves 
slightly differently from the ANSI str- 
rchr function. 



SIMPREQ.C 

Simpreq.c contains the code for a sim- 
ple string requester with Okay and Can- 
cel gadgets. It was generated quickly 
using PowerWindows and wasn't de- 
signed to be particularly pretty. If you 
prefer another string requester, you can 
probably substitute it for this one with 
minimal work. About the only notewor- 
thy piece of code in simpreq.c is the section that decides 
whether to open on a custom screen or on the Workbench: 

if (window) { 

it (scr = window->WScreen) { 
if {((scr->Flags & SCREENTYPE) 
== CUSTOMSCREEN) II 
«ser->Flags & SCREENTYPE) 
= PUBUCSCREEN)){ 
nw.Screen = scr; 
nw.Type = CUSTOMSCREEN; 
} 
} 
) 

Note that you must check not only if the screen the parent 
window is on is a CUSTOMSCREEN, but also whether it is 
a PUBLICSCREEN. In both cases, however, the NewWin- 
dow's Type field should be set to CUSTOMSCREEN. 

EXAMPLE2: ADVANCED ASL 

Demonstrating the ASL requesters' more advanced fea- 
tures, Example2 runs under 2.0 only, takes only window and 
screen as command-line arguments, and exits if it cannot find 
the ASL library. It displays a regular file requester, a multi- 
ple-select file requester, and an elaborate version of the font 
requester. All three are "nonblocking," the type of requester 
preferred by the Amiga User Interface Style Guide. As with Ex- 
amplel, if the window argument is specified, a "parent" win- 
dow opens, then the first requester appears. Now, however, 
when you click in the parent window, the mouse pointer does 
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not change and clicking on the window's close button, Intu- 
ition gadget, or resizing the window, causes messages to be 
displayed in the window. This is accomplished using ASL's 
call-back facilities. 

Example2.c is almost the same as Examplel.c. The differ- 
ences are that OpenStuffQ requires asl. library to be present 
and that the three requesters are called GetFileNamelQ, Get- 
FileNamesO, and GetFontName(). The calling sequence for 
GetFileNamelQ is the same as for GetFileNameQ in Examplel. 

GetFileNamesO is a multiple-select file requester and it re- 
turns a pointer to the struct List. Complete filenames are pre- 
sent in the ln_Name fields of the nodes in this list. The code 
illustrates how to loop over the nodes and print out the se- 
lected filenames. Once the filenames are printed, the list is 
deallocated using NukeListQ (see utile). 

The calling sequence for GetFontNameQ is identical to that 
of the function with the same name in Examplel. 

Instead of using requestersl.c, Example2 employs re- 
questers2.c. Its basic differences from requestersl.c are that 
it uses AllocAslRequestTags() instead of AllocAslRequest() 
and if there is a parent window, the requesters are non- 
blocking and share the parent window's IDCMP. In fact, this 
is a requirement: To be nonblocking, the requester must share 
the IDCMP port of the parent window. In this case, the pro- 
gram calls SetTaskWindowQ, but not SetWindowBusy(). 

For the first example, GetFileNamelQ, the changes are that 
the FILF^NEWIDCMP flag is not set, but the FILF_DOMSG- 
FUNC flag is. In addition, the ASL_HookFunc tag item is set 
to a pointer to FileHookQ, which is elsewhere in this file. Just 
for fun, I added a Pattern gadget and made this a "save" re- 
quester. Note that the case in which the parent window does 
not exist (the pointer is NULL) is automatically handled by 
the requester — it allocates its own IDCMP and everything 
continues to work. Also note that before the call to AslRe- 
quest(), the rf_UserData field is set to the pointer to the par- 
ent window. 

If there is a parent window and, for example, the user clicks 
on the gadget while the requester is up, FileHookQ is called, 
much as FontHookQ was in Examplel. Here, the object is a 
pointer to a struct IntuiMessage and the application can do 
whatever it needs to based on the class of the message. The 
example program simply writes a text message about what 
happened to the parent window. It can do this because it re- 
trieves the pointer to the parent window from the requester's 
rfJJserData field. 

The requester also has the FILF_DOWILDFUNC flag set, so 
for each file FileHookQ is called with a pointer to an Anchor- 
Path structure. All information about the file should be ex- 
tracted from this structure, not from the file-requester struc- 
ture. Specifically, the filename can be extracted from the 
ap_Info field, which is a complete FilelnfoBlock structure. A 
pointer to the lock on the directory that contains the file is 
available in the an_Lock field of the AChain structure point- 
ed toby the ap_Current (or, equivalently, ap_Last) field of the 
AnchorPath structure. FileHookQ will accept all the files; the 
code is here only as an example of how to be more selective 
than is possible using partem matching about the files that are 
listed. If you need to change directories inside this function, 
be sure to get back to the initial directory before returning. 

GetFileNamesO is the multiple-select file requester. It was re- 
markably simple to make it multiple select: I added the 
FTLF_MULTISELECT flag to the ASL_FuncFIags tag item. Re- 
trieving the selected files is, however, a bit more complicated. 



The "easy" way is: 

nfiles = freq->rf_NurnArgs; 
for (i = 0; I < nfiles; i++) { 

strcpyfdir, freq->rf_Dlr); 

AddPart{dir, freq->rf_ArgList[i].wa_Name, MAX PATHLENGTH); 

filclist = AddList(filelist, dir); 
} 

The number of files is returned in the rf_NumArgs field. 
The example uses this to loop over the files and assemble the 
path and file parts into a full filename. The file portion is 
stored in a list of WBArg structures. AddListQ then generates 
an Exec list of full filenames that can be returned to the caller. 
Notice that the full filenames are still in principle "relative" 
paths (relative to the current directory), just as with the oth- 
er file requesters. 

The limitation to the multiple-select requester is that it only 
allows selection of multiple files from the same directory. 
This is implicitly assumed in the way the file and path parts 
are assembled in the above code. If the restriction is ever re- 
moved, the method breaks. 1 therefore recommend you use 
a slightly more complicated procedure to obtain guaranteed 
absolute paths: Change to the directory of the file, obtain a 
lock on the file and use the function NameFromLockQ. The 
relevant code is: 

nfiles = freq->n*_NumArgs; 
for (I = 0; I < nfiles; i++) ( 

oldlock = CurrentDir(freq-> rf_ArgLlst[i],wa_Lock); 

if (oldiock) { 

lock = Lock(freq->rf_ArgList[i].wa_Name, ACCESS_READ); 

if (lock) { 

NameFromLock(lock, fil, MAX_PATH LENGTH); 

UnLock(lock); 

} 

CurrentDir(oldlock); 

} 

fllellst = AddList(filelist, fil); 

) 

The last example in requesters2.c is a more elaborate ver- 
sion of the Examplel font requester. A few flags and an 
ASL_ModeList tag item were added. The example, howev- 
er, doesn't do anything with the selected font styles, modes, 
or colors. The main difference is really in FontHookQ, which 
now deals with the parent window IDCMP messages. Notice 
that for IDCMP messages, both FileHookQ and FontHookQ 
must return the pointer to the object, because the requester 
still needs to reply the message to Intuition. 

FINAL REMARKS 

The basic operation of the ASL requesters is remarkably 
simple. On the other hand, the requesters are very flexible 
and can be equipped with lots of bells and whistles. After 
reading this article, you should not have any excuses left for 
not using ASL requesters in your applications. ■ 

Willy Langeveld is a physicist and scientific programmer at the 
Stanford Linear Accelerator Center (SLAC). He is the author ofa.o. 
VLT ami rexxarplib.library, plus is the moderator of the Ami- 
ga.user conference on BIX. Contact him c/o The AmigaWorld 
Tech Journal, 80 Elm St., Peterborough, NH 03458 or on BIX 
(langeveld). 
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THE AMIGA IS crammed with advanced features that 
many programmers can't reach. All the knowledge of BASIC, 
C, Modula-2, or even assembly language can't provide that 
elusive link to the Amiga's inner workings. Another element 
is needed: learning how to tap the Amiga's architecture. 

Your program must communicate with the Amiga by 
means of calls to libraries, devices, and resources. With such 
calls, you may create, investigate, or modify a host of activi- 
ties within the Amiga. Elements such as screens, windows, 
gadgets, menus, messages, files, processes, and more all will 
go to work at your command. 

No matter what programming language you choose, you 
need to learn how to access the Amiga's rich roster of fea- 
tures. Programming textbooks often focus on the language it- 
self, with limited attention to system architecture. In this col- 
umn I will try to fill that gap, emphasizing the Amiga's 
architecture, and deemphasizing the particular programming 
language you may be using. Examples — complete programs 
or fragments — will be given in two languages, principally 
BASIC and C. 

C: GENERIC VERSUS CUSTOM 

Programs written in C compile into efficient machine lan- 
guage code. While many C programmers write at a relative- 
ly low level (close to the machine's architecture), C comes 
with functions that permit faster program writing and more 
portable code. Each programmer chooses a compromise be- 
tween the two approaches: code that's "close to the machine" 
versus code that uses standardized C functions. 

I call the two extremes custom and generic coding. Most 
programmers use some of each. Generic programming pro- 
duces programs that are easily transportable, but that take lit- 
tle advantage of the Amiga's special resources. Custom pro- 
gramming exploits the Amiga's dazzling operating system, 
but creates programs that often will not travel easily to oth- 
er systems. 

Generic-style programs tend to use C's standard functions. 
Memory is allocated with malloc(), and messages are print- 
ed with printf() or putchar(). Files are handled in "level 2" 
style, using fopenQ, fclose(), and I/O statements such as 
freadQ, fgetcQ, fputc(), or fwritef). 

Custom-style programs tend to address Amiga library 
functions directly. Such programs might allocate memory 
with the Exec library function AllocMemQ; with it, you may 
specify the type of memory desired, such as chip or fast. Mes- 
sages would be printed using the DOS library function 
WriteQ. Files will be opened and closed with Open() and 
CloseQ, again from the Dos library. 
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Because my intent is to show how to access the Amiga's in- 
ner workings, I plan to emphasize custom-style Amiga C 
programming. 

BASIC: IN TRANSITION 

BASIC is designed principally as an interpreted language. 
That usually makes it easier to code and debug, but slower 
to run. Many developers find BASIC a good language to 
rough out logic flow and test concepts. When the logic looks 
sound, the program may be rewritten into a language such 
as C. The best known Amiga Basic is. ..Amiga Basic, of 
course. For many years, Amiga Basic came with your Ami- 
ga at no extra charge. With new Amigas, you must buy it 
separately. Other implementations of BASIC are available 
for the Amiga: F-BASIC (Delphi Noetic Systems), True BA- 
SIC (True BASIC Inc.), and COMAL (Comal User's Group), 
to name only three. Each has its enthusiasts, and all of them 
are capable of being used to explore the Amiga's inner 
workings. 

INVOKING THE SYSTEM 

Your programs will typically interact with the Amiga sys- 
tem by means of two activities. They will call subroutines lo- 
cated in the Amiga's shared libraries; and, as part of these 
calls, they will often make use of structures. Normally, you 
won't peek and poke memory addresses on the Amiga. In- 
stead, you politely ask the system, via its library function 
calls, to do various jobs for you. 

"Shared library" is a phrase that many beginners find con- 
fusing. The word library calls to mind a place where you look 
things up. On the Amiga, shared libraries are much more than 
that: Each is a collection of function calls. The programmer of- 
ten views such a library as a "jump table;" each item in the 
table is a subroutine-call address that invokes a specific Ami- 
ga operation. A close cousin to the library is the device. Again, 
the word is misleading; in this context, device does not mean 
the hardware. Instead, a device is a set of programs to handle 
input and output for a specific piece of hardware. 

The various libraries have names that seem familiar to 
Amiga users. You may recognize the follow iiig names: Exec, 
the master control point of the Amiga; Dos, a major handler 
for input and output, particularly where disk drives are in- 
volved; Intuition, a central clearing house for screens, win- 
dows, keyboard, and other user interfaces; and graphics, a fa- 
cility to help draw into screens or windows. There are many 
other libraries, some of which we'll use only occasionally. In 
total, there are thousands of system calls that we can make 
to the various libraries. 
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When we call one of the many system library functions, we 
may need to deal with structures. A structure is a collection 
of information. To exploit the Amiga, you must use data 
stored within the various structures. 

Consider some examples of structure usage. If we call for 
information about a disk file, using the Dos library function 
Examine(), the result will be supplied to us as a structure 
called a FilelnfoBlock. This structure contains such items as 
the filename, its protection bits, size, comment field, and 
other elements. A program needs to know how to look at 
this structure; for example, that the first character of the 
filename is located eight bytes from the start of the Fileln- 
foBlock structure. 

Here's another example: Suppose you wish to create a new 
window. To do so, your program 
calls the Intuition library function 
OpenWindow(). Before making this 
call, however, you must set out de- 
tails of the desired window, includ- 
ing: its size, its position, and the 
gadgets it have. All this, plus other 
information, must be built into a 
structure called NewWindow; that 
structure; in turn, is supplied to 
OpenWindowQ, which creates the 
window as specified. 

Once you've learned to call a 
function within a system library and 
how to deal with structures, you're 
well on your way to tapping the 
Amiga's power. You can go about 
these activities in several ways, de- 
pending on the programming lan- 
guage. In the final analysis, howev- 
er, they are the same system calls 
and the same structures no matter what language is used. 

THE C APPROACH 

To use the functions of any library, you must first connect 
to it with the function OpenLibrary(). When you're finished 
with the library, release it with CloseLibraryQ. The C lan- 
guage automatically opens two of these for you. 

The pre-opened libraries are Exec and Dos; their reference 
points (library bases) are stored as variables SysBase and 
DosBase. Many programs won't need to use these variables 
directly; the C system will call upon themwhen appropriate. 

All libraries other then Exec and Dos must be opened with 
an call to OpenLibraryQ and, eventually, closed with CloseLi- 
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braryQ. The pointer (library base) returned by OpenLibraryO 
must be stored under its proper symbolic name; C will use 
that name when it's asked to call one of that library's func- 
tions. The symbolic names are easy to remember; the fol- 
lowing code fragment gives the idea. 

struct IntuitionBase "IntuitionBase; 
struct GfxBase 'GfxBase; 

IntuitionBase = (struct IntuitionBase ') 

OpenLibrary("mtuition. library", OL); 

GfxBase = (struct GfxBase ') OpenLlbrary("graphics.library",0L); 

... (main program) ... 

CloseLlbrary(Gf xBase); 

CloseLibrary(lntuitlonBase); 

Here's something that confuses 
beginning C programmers: Intu- 
itionBase, GfxBase, and similar 
items have two separate identities. 
First, the name is used to describe 
(in C terminology, declare) a struc- 
ture; the description usually comes 
from an include file such as intu- 
ition. h. Secondly, the same name 
defines a pointer that the program 
needs to store within its memory. 

I'll try to clarify this double mean- 
ing by describing the code above. 
The first line of code might be read 
as: "Set aside memory for a pointer, 
which will point to a structure of 
type IntuitionBase; call the pointer 
IntuitionBase." C understands the 
two kinds of usage without confu- 
sion. You might find consolation in 
the thought that this kind of thing simplifies the job of choos- 
ing a name for the library base pointers: The pointer name is 
the same as the structure name. 

The same double-purpose name usage is found in the 
OpenLibrary line. Reading the line roughly in reverse, we 
might translate as follows: "Open a library called intuition. 
library, any version. When you get the library-base pointer, 
note that it points at a structure of type IntuitionBase; final- 
ly, store the pointer into variable IntuitionBase." 

About structures: C usually gets declarations for Amiga 
structures from the appropriate include file. When you need 
to handle a structure, check your documentation for names 
of the various fields. +■ 
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Remember that you must get names of libraries and func- 
tions exactly right, including upper or lower case as neces- 
sary. You won't find a library called Dos.library or a DOS 
function called delay; in both of these, the letter D is in the 
wrong case. 

ABOUT AMIGA BASIC 

Amiga Basic ("Microsoft Basic for the Amiga") was de- 
veloped by Microsoft Corporation. 
The language is fully featured and 
fairly fast for an interpreted lan- 
guage. Amiga Basic also has a num- 
ber of features tailor-made for ac- 
cessing the inner workings of the 
Amiga. Libraries are accessed with 
the command LIBRARY, and return 
values from specific function calls 
are given "types" by means of DE- 
CLARE FUNCTION... LIBRARY. 
Structures are most often built with 
two keywords: SADD (String Ad- 
dress), and VARPTR (variable- 
pointer). Keep in mind that BASIC 
strings are not normally terminated 
with CHRS(O); frequently you must 
tack on this character before using 
SADD to set up a pointer to a string. 
Structures are often built as BASIC 
integer arrays; a pointer to their lo- 
cation within memory produced by 
VARPTR. 

LIBRARY signals that the pro- 
gram wants to use one of Amiga's shared libraries and caus- 
es Amiga Basic to issue OpenLibraryQ to the system. 

For LIBRARY to work, a bmap file must have been creat- 
ed for the named library. A bmap file, such as dos.bmap or 
graphics.bmap, should be located in the current directory 
or, preferably, in libs:. To create a bmap file, look on your 
Extras disk, in the drawer BasicDemos. You'll find several 
bmap files, plus the program ConvertFD, which makes 
bmap files. Create the ones you want and copy them to your 
libs: directory. 

By the way, ConvertFD gets its information from a set of 
files named "... fd" that are located on the Extras disk. These 
are text files: Read them! They provide quick documentation 
on the function calls of each library. For example, dos_lib.fd 
holds information on the system calls that we are about to 
make here: Open(), Close(), and Execute(). For more detailed 
documentation on dos.library calls, consult The AmigaDOS 
Manual, Third Edition (Bantam Books). 

FIRST PROJECT 

This first programming technique is a quick trick. It's a 
way of triggering a CLI/Shell command directly from your 
program. Execute(), in the DOS library, performs any com- 
mand as if it were typed into a CLI window. The function 
must be provided with an output file handle (that's an 
AmigaDOS term). We get that by opening a file to device 
NIL:, which gives us a handle to "nowhere." 

The usual method for a program to acquire a disk directo- 
ry involves many calls to functions within dos.library; it can 
get a little tedious. You must first call LockQ, then Examine(), 
and then make repeated calls to ExNextQ; each call gets one 
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directory item. Finally, a call to UnLockQ releases the direc- 
tory. With version 2.0 of the operating system, the work can 
be done using the new function ExAH();, but either way, it's 
a grunt job. We're going to skip all that by using ExecuteQ; a 
CLI command will write a complete directory listing to a file 
of our choosing. 

Incidentally, 2.0 has an interesting alternative to the Exe- 
cute() function. The new function SystemTagList() does the 
same job and allows many options. 
This example, however, employs 
Execute(), which works on all Ami- 
gas. 



THE BASIC SOLUTION 

A couple of quick notes, and then 
we'll go straight to the code. Key- 
words OPEN and CLOSE already 
exist in Basic; so dos.library func- 
tion calls Open() and CloseQ are re- 
named as xOpen() and xClose(). 
Functions Open() and ExecuteQ 
both return a value to the calling 
subroutine; we must assign a "type" 
to this value using a DECLARE 
FUNCTION statement. CloseQ 
doesn't return anything of interest 
to us, so it doesn't need DECLARE 
FUNCTION. 

Now, take a look at the code: 



REM - This demo program shows how to 
REM - Invoke Amiga's DOS library 
REM - EXECUTE routine from Amiga Basic 

' We must use Open/Close to allow 
' operation from Workbench start! 
DECLARE FUNCTION xOpen& LIBRARY 
DECLARE FUNCTION Executes LIBRARY 
1 No need to declare xClose 
' Here comes the code 
LIBRARY "dos.library" 

zS = CHRS(0) 
' Open NIL: as a tile to allow output path 
' Invoke the dos.library Open (as Basic xOpen) function 
' handle = Opon(fllename,mode) 

handle* = xOpen&(SADD("NIL:"+zS),1005) ' MODE_OLDFILE 
IF handle&oO THEN 
■ Invoke the dos.library Execute function 
'success = Execute(commandString, input, output handle) 

x = Execute(SADD("list >RAM:temp"+z$), 0, handled) 
' the file handle to NIL: has done its job; close it 
' Invoke the dos.library Close (as Basic xClose) function 
' Close(handle) 

xClose(handle&) 
' List the directory In RAM:temp 

OPEN "RAM:temp" FOR INPUT AS 1 

WHILE NOT EOFfl) 
LINE INPUT #1,aS 
PRINT aS 

WEND 

CLOSE 

KILL "RAM:temp" 

Continued on p. 55. 
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TOOL CHEST 



ONLY $12.95 EACH 

BUY 2- GET 1 



Quality Software at an Affordable Price! 



Special "Tool Chest Theme" Disks. 

#TSP1. Maps of USA, Canada and Europe Hi-Res hoi, pills and needles. Cinco. Try to ge! five X's in a row 

IFF brushes ol all 50 Slates. 10 Canadian Provinces and before ycur apponenl does Color Logic A Master Mind- 

counlries in Europe. Each map has a 3D extrusion effect like game. 

with cast shadow. ITSP6. 3D Vector Objects #1 Lamp, mirror, bed 

JTSP2. Sounds Animal sounds, musical instruments chair, fire hydrant, lamp post, street lamp, street sign, traf- 

and miscellaneous sounds. 43 sound samples in all. fie light, cannon, cannon supplies, rose, fork, spoon, knife, 

#TSP3. Gamesl 3D TicTacToe. A challenging 3 dimen- plate All objects are in Sculpt formal. 

sional ticlactoe game. Crystal Caverns- A colorful, graphic #TSP7. 3D Vector Objects #2 Books, Early American 

adventure game. DoWot. An adaption ol the classical 2- telephone, barrels, gun. spaceships, lamps, trombone. 

player connect-lhe-dot game. PDMan. A fast maze game bugle, skateboard, Lego-Rover, remote control, glider 

where you deliver pizzas before the monster gels them, airplane. All objects are in Sculpt format. 

TinyBall. The world's smallest baseball arcade game #TSP8. Clipart B&W and colorful clipart for a variety of 

Surround-Cycles. A high-speed arcade game loosely needs. People, holiday clipart, school items, scrolls, food, 

based on the light cycle' races from the movie Tron. monsters, fish, lobster, symbols, and more, 

#TSP4. Games2 Dyno-Wara. A strategic checker-style #TSP9. Utilities #1 fconMeisler. Icon editor with a 

game "Koooties". Assemble a bug before the computer complete set of tools. TJFormat.. A disk formatting 

Blockbuster. Get rid of blocks by pushing matching blocks program. Chartmaster. A graphing tool that allows you lo 

into Ihem. 'Warrior". A fun shool'em-up adventute game, generate and save different graphs. Graph3D. Visualize 

Triton. A tetris-style game. Circe. Battle the computer's complex data in 3-D manner and save the results. 

armies to take over the planet Circe. StrucGen. Create gadget, text, bitmap, and window struc- 

#TSP5. Qames3 CrossCircuil. A one- or two-player lures and write the C source code to disk, LabelMaker. A 

action logic game Word Search Generate your own word very easy-to-use label program DoublePrinl. Prints your 

search puzzles Drugbusiers. Gel rid of cigarettes, alco- text files on both sides of the paper. 



#TC11. (Sept/Oct 89). DiskSalvage mil fix corrupted 
disks and <ecover deleted files IconMeister is an 
advanced Icon editor AlienDuel is a fast, shoot' em- up 
game Crystal Caverns is a colorful, graphic adventure 
game. Plus an animation, sound samples. 3D dinner table 
objects, and Hi-Res monster clipart 
#TC12. (Nov/Dec 89). TJFormat formats disks that 
AmigaDOS chokes on. ChartMaster is a powerful g'aphing 
tool. MoreCandy generates an assortment of colorful 
graphic patterns and saves them to disk Shark, a game 
where you have to eat all the little perch you can catch to 
stay alive. Plus B&W clipart, spaceship 3-D vector objects, 
an animation, and Speakeasy (C source code for the 
programmer who wants to add speech to C programs), 
#TC1 3. Jan/Feb 90). SlrucGen lets you create gadget, 
text, bitmap, and window structures and writes the C 
source code to disk Lifecycles plots your biorhythms 
Create spectacular images VJith Mandelbrots. Look, a CLI 
utility that helps you find files on your disk quickly and 
easily. Plus 3-D objects, holiday clipart, an Amiga Flight 
animation, drive head cleaning utility, and a technical 
discussion on how AmigaDOS stores information on disk, 
»TC14. [March/Apr 90). Amigo Rte is a database & 
addressbook. Graph 3-D lets you visualize complex data In 
3-D manner and save the results, 3-D TicTacToe 
Spectrogram analyzes and displays digitized sound 
Pteronadonaball, an animation by Lou Markoya. Plus 3-D 
objects, food clipart, and sound samples. 
#TC15. (May/June 90). Labelmaker is a very easy 
lo use label program SurroundCycles. a high-speed 
arcade game. Dot2Dot, an adaption of the classical 
connect-the-dot game. Animation by Brad Schenck that 
also is a tutorial on animation techniques. Collection of 
clipart, plus animal sounds. 

ITC16 (July/Aug 90). Cyberscape generates complex 
3-D vector obiects ol terrain and saves your objects in 
Sculpt or Turbo Silver format. Mathplotter graphs mathe- 
matical equations in both 2-D and 3-D. Double Print prints 
your text files on both sides ol the paper. Plus Melamoiph 
(a graphic adventure game), 77ny8a//(the World's Smallest 
Baseball Arcade game), and six digitized sound e'fecls 
#TC21. (Sept/Oct 90). Circe is a "Risk-style' game 
where you rattle the computer to take over the planet Circe. 
Batchrnan allows you lo execute CLI programs, batch files 
and ARexx scripts by clicking on a gadget. Colors prints 
color test sheets and assigns RGB values to printer and 
screen output Easyfle is a powerful database foi home or 
small business. Sprite Edrforlets you create animated 
sprites. Plus 3-D fruit objects, and five sound samples 
±TC22. (Nov/Dec 90}. Amiga ChecWxwJr is a fasl check- 
book manager with check printing ability, budget analysis. 
and a report writer. AmiCrypt is a file encryption/decryption 
tool. WaveSyn lets you design instruments and waveforms 



lor use in other programs. II also lets you play your keyboard 
like a piano. Cinco is a game where you try to ge: five Xs in a 
row before your opponent does AlterCU lets you change 
attributes ol your CLI window with a single command. Plus 
an animation by Lou Markoya, and 3-D objects. 
#TC23. (Jan/Feb 91). Whereis lels you quickly find a 
misplaced file on your drive. Select creates a window Irom 
which you can run your lavcnte programs. MatheMagic lels 
you lind the day ol Ihe week lor any date in the century, 
lets you enter statistical data lo be analyzed, graphs data, 
and solves linear algebraic equations. Pointer List Maker 
lets you create your own pointers or import pointers from 
other programs and save them in a disk file. Dyno4Vars 
requires more strategy and thought than your regular 
checker board game, Plus Mr. Monster and Triton games, 
3-D objects, six sound eflects, and a Pretzel an mation. 
*TC24. (March/Apr 91). TaMeMaAeris a tool for build- 
ing tables of all sorts "Koooties' mis a fun game where you 
have lo assemble a bug before the computer beats you lo 
it. HT (HyperText) lels you put links in a text file to olher text, 
graphics, sound, animation, music, ARexx, and other appli- 
cations. The Little Black Book is a telephone and a a cress 
book. Color Logic is a Master Mind like game. Trie computer 
picks Ihe colored pegs that you have lo guess Ihe positions 
of. Plus four disk and memory utilities, and animal sounds. 



fTC25. [May/June 91). ScreenTcllf captures your 
screen lo an IFF file. PopColors lets ycu change the 
colors of your Workbench screen. 'Warrior' is a fun 
shoot'em-up adventure game for one or two players. 
Kaleidoscope is a line drawing program Blockbusters is a 
game where you get rid ol blocks by pushing matching 
blocks into Ihem. Amidemo demonstrates how fast the 
Amiga does solid-polygon animations. Microscope lels 
you examine memory at any localion in Ihe Amiga Plus 
Hi-Res IFF brushes ol all 50 states and 10 Canadian 
provinces, nine digitized sounds, and two small disk utili- 
ties and one printer utility. 

#TC26. (July/Aug 91). Word Search Maker lets you 
create word search puzzles TimeCalc is useful for anyone 
who has to calculate hours and minutes Dmgbusters is a 
fun game where you get rid ol cigarettes, booze, pills and 
heron needles, Wordfinder lels you search binary or text 
files for a particular word or string. KeyClick will add a 
small click lo your keys when pressed and AtauseC/rdrwili 
add a small beep to your mouse. Seawar is a game 
between the Allied Navy and Ihe Empire Fleet Plus Early 
American 3-D vector objects, digitized sound effects, and 
a simple DIR program 

#TC31. (Sept/Oct 91). Calendar Publisher allows you 
to personalize and print calendars. CrossCircuit is a one- 
or two-player action-logic game that calls 'or last reflexes 
and las! thinking Apr is a llexible printer utility Pizza 
Delivery Man is a last maze game where you deliver 
pizzas in your neighborhood MultiPlayer displays IFF 
pictures or brushes as well as IFF sound samples. Plus 
RAMGauge, 3-D vector objects, and Hi-Res IFF brushes ol 
all maps and flags in Europe. 

#TC32. (Nov/Dec 91). Computer Coloring Book comes 
wilh 15 pages ol pictures lo color Listmaker lels you make, 
edil, combine, and print lists of words Moresmoolh! 
displays text files on the screen Pocket Biliards lels you 
choose from several of the most popular pool games. 
Texlure lets yoou create, manipulate, and save realistic 
fractal textured surfaces, Plus Plague (monster maze 
game), banjo and guitar 3-D objects, Screen Fader, 
SnowBench. and FlipBencn. 

ITC33. (Jan/Feb 92j. Measuresl.O converts measure- 
ments Irom unil or system lo another DiskLabeler is a 
database designed lor storing and printing 3.5' disk labels 
Jewels, a game ol action and strategy. Switch a fun board 
game. GFXclipper captures and saves graphic screens. 
Softball Manager, a database for storing stats for players, 
teams and leagues. WB Exec allows you to execute CLI 
commands Irom WorkBench. Plus Clipart and an index of 
all the back issues ol AmigaWorld Tool Chest. 



ORDER FORM 



Write your selection below and enclose this foim with proper payment. Only $12.95 each.Buy two get one tree! 
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#_ 

#_ 
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Check enclosed 
Charge my: MasterCard 
Amex 



Total disks x $12.95 each (Buy 2 get 1 free) 

Add S3.50 postage/handling for each order 

(Canada & Mexico S5.00, Foreign orders S1 1 .50) 

Canadian orders add 7°i GST 

California Residents add 7.25% Sales Tax 

Total enclosed 



Visa 
Discover 



CARD* 



ADDRESS 



CITY 



SIGNATURE 

Tool Chest • P.O. Box 802 • 80 ESm Street • Peterborough, NH 03458 

1 -800-343-0728 or 1 -603-924-0100 




DIGGING DEEP IN THE OS 



Screens for Public 
^ Consumption 



ON DISK 



ByJohnToebes 



PUBLIC SCREENS ARE a very important but often over- 
looked feature of OS 2.0. If you use VLT or any other program 
that relies on screenshare.library, you're probably already fa- 
miliar with the concept of a program opening up its window 
on the screen of a program other than Workbench. The 2.0 
version of Intuition makes this a standard part of the pro- 
gramming paradigm. 

From the simplest view, public screens have three basic 
users: 

• Applications that create their own screens and hence are 
targets for other windows to open on them. In some cases, 
you might even expect particular applications to be opened on 
the screen. 

• Applications that open windows that might be placed on 
other than the default Workbench screen. 

• A public screen manager that allows the user to control 
these interactions. This category, of course, is very limited in 
the number of possible applications (how many screen 
blankers do you expect to run?), while the other two cover 
just about every program that can be written. 

To the user public screens can be a real benefit. Applica- 
tions that previously could not be displayed at the same time 
(such as an editor and a terminal package) can now be com- 
bined easily at the user's discretion. This, combined with the 
existing ARexx support, allows for some truly integrated ap- 
plications. 

Fortunately, public screens were designed with the normal 
programmer in mind. There is very little that an application 
has to do to support them, but you must give them careful 
thought. 

CREATING A PUBLIC SCREEN 

By definition, public screens mean that any program can 
open up on a screen. From the screen side there are few im- 
plications, but tlie application creating the screen and win- 
dows must be aware that other windows may overlap its 
windows. For this reason, you can no longer assume that 
things such as front-to-back gadgets are unnecessary. Tlie 
most common mistakes are: 

• Using a S1MPLE_REFRESH window with NOCARERE- 
FRESH set, because you assume that no other window will 
be present. 

• Using the SCREEN bitmap for rendering directly. 

• Not including front-to-back or sizing gadgets when other 
windows occupy the same screen. 
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• Creating a BACKDROP window and expecting it to be the 

topmost or only window. 

Fortunately, these are easy to check for and remedy. The 
first one requires changing to either a SMART_REFRESH 
window or implementing appropriate refresh routines. Ap- 
plications that use the SCREEN bitmap are probably not suit- 
able candidates for public screens. The last two have some 
window presentation implications, but the 2.0 look and feel 
brings enough changes that you probably have to change 
your application in this area anyway. 

In addition to ironing out these issues, your program must 
also include a couple of new routines to create a public screen. 
The most important is OpenScreenTagListQ. Tags are the 2.0 
way of passing many of the new optional parameters to sys- 
tem routines. OpenScreenTagListf) accepts three tags: 

• SA_PubName: Indicates tlie name of the public screen. If 
this tag is not present, the screen is not public. If it is present, 
the ti_data field should point to the NULL- terminated name 
for the screen. 

• SA_PubSig, SA_PubTask (must be give as a pair): The task 
and the signal bit to use to notify you when the last window 
on the public screen is closed. Make sure that they appear in 
the tag list after the SA_PubName tag. 

Although not specific to public screens, the SA_ErrorCode 
tag is useful for figuring out errors. The tag's ti_Data field is 
a pointer to a LONG that holds the return code from Open- 
ScreenTagListQ. If you do not supply this, you will have no 
idea why the screen failed to open. 

As you can see, a public screen is identified by its name. 
Because of this, each public screen must have a unique name. 
Generating it is probably the hardest thing to do for an ap- 
plication — particularly when you may wish to run multiple 
copies of the application at one time. How you solve this 
problem is dependent upon how you expect the application 
to run. Obviously, a hardcoded name is not a good choice. 
Your alternatives are: 

• If the public screen is already open, ignore the failure to 
open another public screen of the same name and default to 
letting the application use the previously opened screen in- 
stead of the current one. For such programs as text editors and 
word processors, this may be a very good implementation. 

• Permute the name by adding a count to the end or the cur- 
rent time, and then try again. 

• Fail the operation. If you really can allow only one copy to 



"~ 



run at a time, this will certainly guarantee it. 
• Make the name of the public screen the same as the ARexx 
port of your program. This method is extremely appealing 
because most programs now have to implement ARexx ports 
and already solve the name-uniqueness problem for them. 
Most likely your ARexx port name was generated by per- 
mutations or even by a user command-line option, so you can 
avoid duplicating code. This has the added bonus of pro- 
viding a common external name that other applications can 
use in interacting with your application. 

With the above requirements fulfilled, all you need to open 
the screen is a routine such as: 

static ULONG oserror; 

static char name[50] = "AW_PublicScreen"; 

/■ I accept the default pens, but have to 

■ pass something to get the new look. 

•/ 

static UWORD sa_pensQ = { 

o, 1, -o /• just detail and block '/ 
); 

struct Tagltem nsextfj = { 

(SA_PubName, (ULONG) ps_name }, 
{ SA_ErrorCode, (ULONG) Soserror }, 
{ SA_Colors, (ULONG) colorspecs }, 
{ SA FullPalette, (ULONG) TRUE }, 
(SA_Pens, (ULONG) sa.pens ), 
( TAG_DONE, } 

): 

static struct ExtNewScreen ExtNewScreeen = 

1 



0, 0, STDSCREEN WIDTH, STDSCREENH EIGHT, 2, /* top, left, width, 

height, depth 'I 
0, 1, HIRES, CUSTOMSCREEN, f Detail, block, viewmodes, type */ 
NULL, NULL, /* font, title (use Pubscreen name) */ 

NULL.NULL.NULL /* gadgets, bitmap, extension V 



struct Screen 'openPubSereenQ 



{ 



struct ExtNewScreen ns; 
struct Screen 'screen; 
int count = 0; 



il (oserror la OSERR PUBNOTUNIQUE) 

return(NULL); 
r Someone else has the name, so try lor the next one 7 
sprintf(name, "AW PublicScreen %d\n", count++); 

} 

PubScreenStatus( screen, OL ); f make the screen available V 
return ( screen ); 



) 



This code is very similar to how you would open an exist- 
ing screen, but adds logic to generate a unique name and a call 
to make the screen publicly available. Public screens have both 
a public and a private status; typically you make a public 
screen private when you are attempting to close the screen 
down. If you want to do some preparation on the screen be- 
forc allow ing other windows to open, you may wish to delay 
the call to PubScreenStarus(). The key to remember is that once 
you switch a screen to public status, you must assume that any- 
one {and possibly everyone) can open up on the screen. 

CLOSING A PUBLIC SCREEN 

Opening a public screen is the easy part. When you have 
several visitor windows on your screen and you want to ter- 
minate the application the trouble really begins. Your choic- 
es for a solution are: 

• Attempt to close the screen as normal. If an error occurs (be- 
cause there are visitor windows), display a requester and 
retry the operation after the user selects OK. This is the ap- 
proach that the 2.0 Workbench uses. 

• Use the SA_PubSig and SA_PubTask tags on OpenScreen- 
TagList{) to make your task wait for the signal before shut- 
ting down. In this way it can do a friendly wait before clean- 
ing up. You still have the general problem of keeping a 
potentially large program in memory just to close a screen, 
however. 

• Spawn a separate process to wait for the signal and termi- 
nate the window when the signal is received. This allows 
your main application to terminate without worrying about 
the window, but requires a bit more work in getting the sep- 
arate process running. One nice thing about this process is 
that it can be shared by multiple applications. 

static struct EasyStruct myezreq = ( 

slzeof (struct EasyStruct), 0, 
"Close Public Screen*", 



while ( screen != OpenScreenTagList( &ns, nsext ) ) 



"Please Close All Windows on this Screen", 
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"OK" 



I; 



void closePubScreen(screen) 
struct Screen 'screen; 

{ 

PubScreenStatus( screen, 1 L ); r make the screen unavailable 7 
while (!CloseScreen(screen)) 

{ 

r The screen didn't close, prompt the user for a chance to try 

again 7 

EasyRequestArgs( NULL, Smyezreq, NULL, NULL ); 
} 
} 

OPENING A VISITOR WINDOW 

Applications that want to open windows on a public screen 
have very little set-up work to do. They need only specify the 
public screen name they wish to open on when they make the 
call to OpenWindowTagList(). Like OpenScreenTagListQ, 
OpenWindowTagList() recognizes a few tags: 

• WA_PubScreenName: Specifies a public screen to open on 
by name. The tiJData field points to a NULL-terminated 
string. 

• WA_PubScreen: Specifies a public screen to open on by ad- 
dress. In this case, ti_Data points to the actual Screen struc- 
ture. You must make sure that the screen will not close dur- 
ing the call. 

• WA_PubScreenFallBack: A Boolean that 
indicates whether Intuition should use the 
default public screen (or Workbench) if the 
named public screen isn't available. 



When you pass a screen by the address, 
you must ensure that the screen is not go- 
ing to close. To accomplish this you can 
lock the screen open with the LockPub- 
ScreenQ call or be certain that a window 
that won't go away is already opened on it. 

To lock a public screen, call LockPub- 
Screen( name ), passing the null-terminat- 
ed name of the public screen as name. If the 
screen exists, you will get a lock on it and 
the function will return the pointer to the 
screen. Otherwise you will get a NULL 
pointer. Once you have safely opened your 
window on the screen, you must call UnlockPubScreen 
(name, screen) to release the screen so that it can be eventu- 
ally freed. 

Given the ease of opening a window on a public screen, 
you should also add a little piece of power to your programs 
to take full advantage of public screens — screen jumping. Be 
warned: Accomplishing this task might take a bit of code re- 
structuring and introduce some issues you may not be ready 
to tackle. The most important of which — resolution and font 
independent code — is beyond the scope of this article. As 
your application window jumps from screen to screen, you 
can see complete differences in layouts because of larger fonts 
or screen resolutions. Jumping to a lower resolution screen 
may cause you to have to seriously shrink a window. 

To prepare for jumping, your application needs to be able 
to close down the window at any time and then reopen it. If 
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you put all your initialization and termination into a single 
place, this is easy. If you have it all mixed in with the gener- 
al initialization code, it might take a while to get it all staight. 
You must also handle how the user specifies the jump oper- 
ation. Do you jump to a specific screen by name, to the "next" 
available screen, or to a screen selected by the user (such as 
the front-most screen). The choice of implementing this is up 
to you, but remember that the user is requesting the opera- 
tion, so it should be built in as a fundamental part of the user 
interface. 

Once you have determined that the user wants you to jump 
to a new screen (probably by a key sequence or menu oper- 
ation), you need to close down the window. Next, locate the 
screen to jump to with NextPubScreenQ and lock it. Now, re- 
open the window on that public screen and unlock the screen. 
Because it is possible for the screen to disappear between the 
time you identify it with NextPubScreenQ and the time you 
actually lock it, you can completely eliminate the lock and un- 
lock steps by taking advantage of how OpenWindowTag- 
ListQ works: 

void dojumpO 

{ 

char buf [150]; 

/* Make sure we can find a new screen before closing the window */ 
if (NextPubScreen( curpubscreen, but)) 

{ 

/• As everything is now modular, just close the old window and 7 
I* open the new one on */ 
/* the new screen. */ 
CloseMy Window)); 
OpenMyWlndow(buf); 
} 
} 
struct Tagltem wintagsQ = { 

( WA_PubScreenName, (ULONG) NULL }, 
{ WA_ PubScreenFallBack, (ULONG) true }, 
( TAG DONE, ) 

}; 



void OpenMyWindow(narrie) 
char 'name; 

{ 

struct Window 'win; 

wlntags£0].tl_Data = (ULONG)naine; 

... Other window structure information based 

on application ... 
win = OpenWindowTagList(Snw, wintags); 
if (win = NULL) 

{ 

I' ooops, we can't get the window open, we might want to go 
back to 7 

/' a previous screen (if we can) or just fail the application. 7 
/' This is a sticky situation that needs to fit the application. */ 
/' remember that you might not even be able to reopen the win- 
dow on 7 
I" the original screen. 7 

J 

Remember that your application needs to handle the 
changes in the screen behind the window. If you have cached 
colors, they will certainly change, as well as aspect ratios and 
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Official Home of the 
Commodore Technical Team 

If you're afflr technical know-bow, there's only one place to get the answers 
you need fastmnd that's on BIX (BYTE Information Exchange). 

m 
BIX is the official home of the Commodore Technical Team of prominent 

Amiga devMopers and Commodore AJpRitioris and Technical Support staffers. 
Tap intqrthe Amiga Technical Team on BIX in these conferences: 



amiga.user 


Exchange ideas, solve problems, compare notes 


amiga.sw 


Amiga programming and developer issues 


amiga.hw 


Amiga hardware design, use, and hookup 


amiga.arts 


Artistry using the Amiga 


amiga.int 


Developing for the international Amiga 


amiga.special 


Special guests and events 


amiga.unix 


Unix on the Amiga 


amiga.games 


Games on the Amiga 


amiga.com 


Commodore's conference for commercial developers 


amiga.dev 


Commodore's conference for all developers 


amiga.world 


Amiga World magazine 


aw. tech journal 


Amiga World Technical Journal 



Check the Fishdisk library index and make an inquiry for the programs you 
want. Search extensive databases of Amiga "how to" reference materials and 
find remedies to your problem. Or join in on "how to" sessions designed to 
show you how to get more out of your Amiga. 

Call BIX today, the official home of the Commodore Technical team and by 
far the most technically oriented on-line service for Amiga users. 



EIX 
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One Phoenix Mill Lane Peterborough, NH 03458 800-227-2983 (voice) 
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\V Spritely Rendering 



By Leo L Schwab 



OCCASIONALLY, YOU MAY need to put dynamically 
rendered imagery into a sprite. That is, a static image in chip 
RAM won't do; you need to actually draw it. Unfortunately, 
because of the way sprites are represented in memory, using 
the rendering functions in graphics.library is, at best, nonob- 
vious. Once you understand how to attach a RastPort to a 
sprite, however, you can easily perform standard rendering 
operations. 

THE PROBLEM 

Figure 1 illustrates the primary difficulty. The Amiga 
graphics functions are designed to operate on bitplanes that 
are scattered throughout memory, and each plane must be a 
complete unit. Sprites, on the other hand, are a different an- 
imal. The bitplanes for a sprite are sort of stuck together side- 
ways. A single line of sprite imagery is arranged as pairs of 
VVORDs, The first WORD in each pair represents the low-or- 
der bits of the sprite pixels (plane zero, so to speak), the sec- 
ond represents the high-order bits (plane one). The sprite 
hardware puts these together and displays three colors plus 
transparency. What's more, each sprite has a little "cookie" 
at the top and bottom, which contains positioning control in- 
formation for the sprite hardware. You definitely don't want 
to draw into those areas. 

Somehow, you must "split" the pairs of image WORDs so 
that graphics functions can operate on them as if they were 
separate planes. You also need to keep from drawing over the 
control WORDs. 

MAPPING THE BITS 

The solution to attaching a RastPort structure starts with a 
BitMap structure, so we'll begin there. 

The BitMap must be formatted such that each line in each 
bitplane begins in exactly the same horizontal position as the 
previous line. In other words, for the first WORD in an im- 
age pair, we want to describe a BytesPerRow width that, af- 
ter advancing that many bytes in memory, will leave us at the 
first WORD of the next image pair. 

At first glance, this might seem to be two bytes (one 
WORD), because that's the width of a single plane. Advanc- 
ing two bytes, however, would leave us in the second WORD 
of the current image pair, which isn't right. If we were to ad- 
vance four bytes (two WORDs), we would skip over the sec- 
ond WORD in the image pair and end up at the first WORD 
in the next pair, which is precisely what we want. 

For the second WORD in an image pair, the increment is 
exactly the same; two bytes to take us to the next image pair, 
and two more bytes to skip to the second WORD in that pair. 
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Thus, we should initialize our BitMap structure to have a 
BytesPerRow value of four, or 32 pixels. 

The height of the BitMap is set to the height of the visible 
sprite imagery. The position-control WORDs are not includ- 
ed in the height. The depth of the BitMap is two planes. 

Finally, the plane pointers must be initialized. Plane is set 
to point to the first WORD of the top line's image pair (past 
the position-control WORDs). Plane 1 points to the second 
WORD of the top line's image pair. 

It sounds complicated, but it really isn't. In C, the whole 
thing is done as follows: 

struct SlmpfeSprlte 'spr; 
struct BitMap "sprltebm; 
PLANEPTR spritedata; 

InltBilMap (spritebm, 2, 32, spr->height); 
spritedata = (PLANEPTR) spr->posctldata; 
spritebm->Piane[0] = spritedata + A; I! Past position control 
spritebm->Plane[l] = spritedata + 6; // Second word ol image pair 

HOW IT WORKS 

Creation of the BitMap is the core of this trick, so it's worth 
spending a little extra time on this point to understand why 
this works. 

If you've read the Amiga Hardware Reference Manual (Ad- 
dison- Wesley), or Tom Rokicki's articles on the Blitter (such 
as 'The Complete Guide for the Blittering Idiot," p. 2, Octo- 
ber '91), you know that the Blitter operates on rectangular re- 
gions of imagery. To do this, the horizontal and vertical di- 
mensions of the area are described to the Blitter so that it 
knows how much work to do. This is why the BitMap struc- 
ture exists. It describes the width and height of the imagery 
to graphics.library. Graphics then takes these values, con- 
verts them into the appropriate hardware values, and feeds 
them to the Blitter. 

Often, however, you don't want to operate on the whole 
image, just a small part of it. The Blitter can be told to touch 
only the part you want and skip over the rest. The amount to 
skip is called a modulo. When doing blits, graphics.library 
figures out how much to skip by subtracting the width you 
specify from the total width of the bitmaps affected. 

The fields BytesPerRow and Height in a BitMap structure 
describe the total size of a bitmap. Graphics.library makes par- 
ticular use of BytesPerRow to calculate modulo values. For ex- 
ample, if you did a blit operation two bytes wide into a bitmap 
six bytes wide, the graphics.library would program the Blitter 
(in the simplest case) to write two bytes of data and skip four 
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bytes to get to the next line of im- 
agery. This is the core of the tech- 
nique — getting graphics.Iibrary to 
set the modulos up just right. 

Recall that sprite images are two 
bytes wide, but that it takes four 
bytes to advance from one line of 
imagery to the next. So, we tell 
graphics.Iibrary that our bitmaps 

are four bytes wide. The fact that only the first two bytes of 
each line are valid doesn't matter; we just make sure we don't 
draw outside the valid area. In addition, it doesn't matter that 
the bitplanes we described overlap each other in memory. 
Neither graphics.Iibrary nor the Blitter care if the planes over- 
lap. They treat each plane as a single unit no matter where it 
is. By restricting our rendering to the first 16 pixels, graph- 
ics.Iibrary will draw into the first two bytes of each plane and 
skip the other two. 

The final effect is that the individual WORDs of the image 
pairs are written to separately, as if they were ordinary- 
planes. Thus, normal rendering is accomplished in a sprite. 

GETTING A HANDLE ON THINGS 

To use the higher-order rendering functions (MoveO, 
DrawO, AreaFillO, and so on), graphics.Iibrary requires a 
RastPort structure. After creating a BitMap structure for the 
sprite, attaching a RastPort is comparatively trivial: 

struct RastPort rp; 

InltRastPort (&rp); 
rp.BltMsp = spritebm; 

Like the RastPort attached to an Intuition screen, this Rast- 
Port does not protect against rendering into invalid areas. 
Thus, you must perform all the clipping yourself. If you'd 
prefer to let the system worry about clipping, you can attach 
a Layer to the sprite and render through its RastPort. You do 
so as follows: 

struct RastPort 'rport; 
struct Layerjnfo "!i; 
struct Layer 'spritelayer; 

If (!(li = NewLayerlnto ())) 
die ("NewLayerlnfo() falled.\n"); 

if ([(spritelayer = CreateupFrontLayer (li, spritebm, 
0,0, 




15, spr->height - 1, 
LAYERSIMPLE, NULL))) 
die ("Create layer failed.W 



rport = spritelayer->rp; 



THE EXAMPLE PROGRAM 

The program drawsprite in the accompanying disk's 
Schwab drawer creates a sprite, attaches a RastPort, and ren- 
ders text into it. The above techniques are collected in the 
function GetSprRendEnv(), which procures a rendering en- 
vironment for a sprite. 

GetSprRendEnvO accepts a pointer to a SimpleSprite struc- 
ture and a Boolean. The SimpleSprite structure is used to cre- 
ate the BitMap and RastPort structures. The Boolean indicates 
whether or not you want a Layer to clip your rendering in 
the sprite. If so, it will create a Layer and attach it to the 
sprite. Otherwise, it will create a simple RastPort. 

GetSprRendEnvO returns a pointer to a pointer to a Rast- 
Port. That is, it returns: 

struct RastPort " 

You can't use the pointer it returns directly. You must fetch 
the RastPort pointer out of the pointer it returns, as shown: 

struct RastPort •rport, "rendenv; 

rendenv = GetSprRendEnv (sprite, TRUE); 
if (rendenv) 
.rport = 'rendenv; 

If GetSprRendEnvO returns NULL, the operation failed, 
and nothing is allocated. 

When you are finished, you should call FreeSprRend- 
EnvQ to deallocate the resources procured with Get- 
SprRendEnvO. The routine automatically figures out 
whether you have a Layer attached and frees it. You pass 
in precisely the same pointer you got from GetSprRend- 

Continued on p. 63 
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By JohnGerlach, Jr. 



WITH AMIGAVISION, COMMODORE redefined the 
concept of multimedia presentation systems, letting you 
easily create applications by placing nonintimidating icons 
on a grid. This ease requires that programmers give up cre- 
ative control, and that users need to have a lot of memory 
to run the application, right? Wrong. I'll show you some 
simple ways to reduce your work and the amount of mem- 
ory needed for even large, complex applications. 

AV is a perfect prototyping and development environment 
for many types of projects, including multimedia applica- 
tions. The one attribute common to all multimedia applica- 
tions is the large amount of information required to compre- 
hensively and compellingly convey the topic at hand. 
L nfortunatdy, AV is sometimes discredited for its demands 
on system memory. Versions 1.70 revision Z and above do 
not use as much memory you might assume they do at Erst 
glance. Using AV's newer features to control memory usage 
allows very complex applications to be run on machines with 
only one megabyte of memory. 

AV1.71Z's disk size of over 590K is not an accurate mea- 
sure of the amount of memory required when using the pro- 
gram. Overlays curtail memory requirements so the RAM 
consumed by code is never equal to the space used on disk. 
In fact, when the executable is started by double-clicking on 
an application's icon, the maximum memory consumed by 
AV is approximately 250K (this playback-only configuration 
may also be initiated from CLI with an -a<filename> speci- 
fication). CATS is currently controlling the distribution of 
"player" versions of AV which do not contain any of the edit- 
ing environment code, thus dramatically lessening the 
amount of disk space consumed. 

DEFAULT CODING MODEL 

A negative attribute common to many AV applications is 
that the programmer was too soon satisfied with what I'll call 
the default coding model. In this model, the code directly re- 
flects the pattern of movement that the end user will follow, 
as a "bird's-eye" view of the application would show the de- 
fault presentation of information. In other words, if the ap- 
plication were to ask a series of questions, the flow would eas- 
ily exhibit each question's display and user-interactions, in 
direct succession. 

For reference, consider an application that serves as an in- 
formation kiosk used to query prospective music buyers. The 
application is to ask each participant questions about their 
musical preference, price limitations, and other such details. 
After the customer gives enough information, the kiosk might 
make selection recommendations, print coupons, and so on. 
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The general assumptions made for the application are: 

1. An "attract loop" is presented while the kiosk is idle to at- 
tract the interest of passers-by. 

2. The application should allow for many types and formats 
of questions, making no restrictions on the number of an- 
swers available at any time. 

3. The response to any question may modify the default 
movement through the remaining questions. In addition, 
nonactivity on the user's part forces the attract loop to restart. 

4. It must be easy to modify the questions and highlights of 
the kiosk as dictated by marketing issues. 

In the default coding model, the resulting application 
would be a long and narrow flow that repeats the sequence 
of displaying a picture, adding hitboxes to let the user make 
a selection, and determining how to react to the selection. 
AV's editing environment makes this type of coding as easy 
.)-- possible by letting you duplicate sections by dragging a 
copy of an existing icon. You often end up, however, with 
an application that is difficult to maintain and modify: You 
have to deal with many similar looking and functioning sec- 
tions of code and force the logic for every question to con- 
stantly reside in memory, even though the customer can only 
interact with one question at a time. 

Even worse than the repetitive coding is the necessity of 
supporting the third assumption. Yes, AV has two Goto icons, 
but indiscriminate use of these teads to unmanageable code. 
Because all questions need to return to the attract loop, you're 
guaranteed to have multiple branches between parts of the 
application that cannot be on-screen at tine same time. 

Being able to easily modify the data presented by the kiosk 
without worrying about corrupting the basic playback mech- 
anism is paramount for assumption number four. If several 
questions are added to a musical classification in the middle 
of the application, and the modification results in an endless 
loop between only a few questions, your customers will not 
benefit from the service you are trying to provide. 

A PRESENTATION "ENGINE" 

Don't give up; you can use this default coding model as a 
verbose prototype of a smaller and simpler method. To over- 
come all of the shortcomings of the default model, fragment 
the application into multiple parts and factor out anv simi- 
larities. This will lessen the amount of memory required, 
while potentially easing the burden of authoring, debugging, 
and supporting the code. 

The key to this process is to separate the application's in- 
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formation from the rudimentaries of its operation. With AV's 
integrated database support, it is easy to have an application 
rely on information contained in a series of database records. 
Furthermore, you can let the database control the presenta- 
tion sequence by adding control 
information to these records. 

Using such a database, the AV 
application can be transformed 
into a presentation "engine," 
which you can construct in a com- 
pletely general manner for reuse 
in multiple applications. This dis- 
tributes the cost of its already short 
development and allows you to 
create subsequent applications in- 
side a familiar and previously test- 
ed environment. 

A presentation engine operates 
on information found in the 
database by repeatedly reading the 
"current" record and performing 
the action it specifies. This process 
can been condensed into a loop 
that performs a database access at 
the beginning of each iteration. 
The information contained in each 
record defines the specifics for the 
current iteration, but may also con- 
tain default settings for the next. 

In the example database, each record contains a default 
next-record value. If the current iteration's code desires to 
modify this default (to force a return to the attract loop, for 
example), it simply overrides the stored value. Otherwise, the 
movement dictated in the database is followed. 

One means of lessening the amount of memory used by a 
complex application is to use the chaining feature in version 
1.70. Chaining allows multiple flows to be connected during 
runtime, giving you control over the amount of memory con- 
sumed by the code. The second assumption in the example 
forces you to allow plenty of resources for each of the ques- 
tions. For this reason, only one question should be present in 
memory at any given time. The code for each question will 
be loaded and started by the presentation engine only when 
it is needed. If these flow files are kept small, their loading 
from disk can easily be masked by other operations. 

AV's chaining has two forms: Link mode and Call mode. 
Link mode starts the new flow and then purges the memory 
used by the previous code. Call mode treats the new flow as 
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a disk-based subroutine that is loaded and executed, being 
removed from memory when it terminates. Chaining in both 
modes is performed without the loss of variables created by 
the parent. When using Call mode, modifications made by 
the child to the parent's variables 
are retained after the child termi- 
nates. In Call mode, the child flow 
can actually create new globals to 
be used later by the parent. The 
new function definedf) can be 
used to determine if a variable 
with a specific name is defined. 

To drive the engine, I con- 
structed a sample database con- 
taining records with the fields: 



• THISRCRD: A key field used 
when selecting a record in the 
database. 

• NEXTRCRD: The default next- 
record number. The value re- 
trieved from the database may be 
overridden as detailed above. 

• AVFN AME: The name of an op- 
tional .AVf file that is chained to, 
if specified. 

• SCRNNAME: The name of an 
optional ILBM file. 



If the current record contains an .AVf filename, the engine 
loads and executes the file. This flow may wish to modify the 
next record number or leave the default value in place. If no 
.AVf filename is specified, the engine simply displays the ap- 
propriate picture, delays for two seconds, and continues with 
the default next record as instructed. This internal/external 
distinction is completely arbitrary. It is entirely up to you to 
determine which operations should be coded directly into the 
engine and which should be placed in individual child flows. 
Note that it would be simple to create a generic Yes/No child 
flow that loads the ILBM file specified in the database and 
uses generic response areas for the user interaction. 

The example assumes that "question" is the attract loop, 
and normally this flow would be as flashy as possible. It is 
started when the program first runs and after each respon- 
dent completes the questionnaire, continuing until the next 
person signals an interest to participate. At that time, the en- 
gine is instructed to present question number one, which be- 
gins the query of the participant's opinions. i 
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The flow file AttractLoop.AVf (in the accompanying disk's 
Gerlach drawer) contains the logic behind an ultra-simplis- 
tic (boring) attract loop. It also shows how the default next- 
record value can be modified by a chained flow, resetting it 
to zero when the engine is not supposed to continue with the 
presentation. This allows the attract loop to ignore the ne- 
cessity of coding a looping action. Also note that any of the 
child flows can use this method of forcing a return to the at- 
tract loop without the need for a single Goto icon. 

You are now free to make maximum use of the computer's 
resources, because chaining frees the code for each question 
as soon as it is completed. An attract loop should make de- 
mands on the system's ability to attract attention by showing 
flashy pictures and making interesting noises, but it proba- 
bly does not need a lot of analysis coding. On the other hand, 
a question may depend on previ- 
ous responses and may lessen its 
user-interaction demands to allow 
code space for complicated infor- 
mation analysis. 

Development of these child 
flows can occur quite rapidly for 
several reasons. First, currently 
loaded flows can be duplicated 
simply by pressing the key com- 
bination Right- ALT-F1 while the 
window is active. This results in 
an exact duplicate of the original 
window that is named Untitled. 
You can then make modifications 
and save the flow to disk. This 
ease in duplication can be used to 
speed test different approaches to 
the same issue. Second, when a 
presentation is started from the 
editor and chaining is specified, 
AV searches the files currently 
open in the editing environment 
before loading it from disk. This 
lets you create a test version of the 

editor without saving to disk and changing the filename in 
the database. 

INTEGRATED DATABASE CREATION 

The example described above assumes that development 
is done in two discrete phases — database creation and ap- 
plication development (and testing). For each iteration dur- 
ing this process, you must enter AV's database editor, load 
the database file, select and edit one or more records, exit the 
database editor and reintroduce the flow. This repetition 
wastes time and can quickly become annoying. 

A logical extension to the example is to incorporate the 
database editing process into the main flow, so that the run- 
time environment need not be exited when modifying the 
current data or adding new records. The example flow con- 
tains a Key Interrupt icon tied to an IfThen icon that relies 
on the state of the variable Development. The variable is de- 
fined in the first X/Y icon and can be modified to control 
the availability of the database-editing feature. Set the vari- 
able to TRUE during development to make the interrupt 
available. To enter the database editing section while test- 
ing, simply press the Fl key. When beta testing your appli- 
cation, set the variable to FALSE so that users cannot mod- 
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ify the data. Of course, all icons specific to editing can be re- 
moved when the project is completed, 

EXAMPLE ON DISK 

The example in the Gerlach drawer on the disk is divid- 
ed into three flows. The first, Engine.AVf, is the engine de- 
scribed above, made nongeneric only by the first X/Y icon. 
This icon controls the activity of the interactive database 
editing, and the name of the database file and the project's 
working directory. The remainder of the example relies 
heavily on variable substitution available through AV's 
bracket notation. All dependencies on the presentation's di- 
rectory use the contents of the variable ProjectDir. To move 
the application to another volume, simply copy the com- 
plete directory structure and change the value assigned at 
the beginning of the flow. 

Likewise, the name of the data- 
base is assigned to a variable. This 
is really only useful if some logic 
is needed to determine which 
database the presentation engine 
uses. For instance, before entering 
the main loop, the flow could ask 
each user to select an area of in- 
terest. This code would then ini- 
tialize the variable so the engine is 
controlled by the music database 
instead of, say, the kitchenware 
database. 

This variable substitution is best 
exemplified by the icons named 
"Execute flow as a subroutine" 
and "Display image." Both show 
how you can use more than one 
variable to construct the name of a 
resource. Specifically, the screen 
icon shows how powerful one 
icon can be. Using two variables, it 
presents any picture supported by 
AV, without the Intuition pointer, 
starting with a fade-from-black transition. A series of simi- 
larly named pictures could be displayed by adding [counter] 
to the end of the filename and controlling the variable 
through a Loop icon. 

The second flow file, AttractLoop.AVf, contains tin- 
specifics to our default "question." While nothing in this 
flow is particularly spellbinding, it no longer retains the 
Module icon given when opening a new flow window. This 
gives a slight size and speed increase, while reinforcing that 
Modules need not be the first icon in every flow. 

The code in the third flow, DataBaseEditor.AVf, allows in- 
teractive creation and editing of database records. Variables 
used only for editing are defined inside the icon "Create 
DBaseOP locals" so that they are not allocated until editing 
is requested, and so that they do not remin after the editing 
process has ended. 

Feel free to use these flow files as patterns for your own 
presentation engines. ■ 

John Gerlach, jr. is Director of Softioare Development for IM~ 
SATT Corp., the creators of AmigaVision. Contact him c/o The 
AmigaWorld Tech Journal, 80 Elm St., Peterborough, NH 
03458, or on BIX (jgerlachjr). 
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Object-Oriented Display Refreshing 



CallLists is a refreshing way to keep your 
interactive programs up to date. 



By Bryan Ford 



INTERACTIVE PROGRAMS (containing complex user in- 
terfaces) pose problems that you don't have to deal with in 
batch processing programs. When writing a batch program, 
such as a compiler, you process a complete set of input data 
in a certain format and write it out in another format. An in- 
teractive program, on the other hand, has to process input 
data that comes from the user in little pieces at a time (events). 
These events usually are entered in no particular order, and 
often change or even reverse the results of previous events. 
An interactive program must generate new, updated output 
very soon — no user likes to wait for a slow program — after 
each input event. 

This article deals with one of the main problems in writing 
interactive programs: refreshing the various parts of a pro- 
gram's display at appropriate times. Some programs have 
many different windows, possibly with several separate dis- 
play areas in each window. When some part of the project is 
changed (a new event is received), the program must imme- 
diately update the appropriate windows to reflect the changes. 

Probably the simplest method of refreshing displays is to 
create one big function that calls all other screen refresh func- 
tions one by one: 

void RefreshAII() 



{ 



RefreshViewsO; 
RefreshQuickMenuQ; 
RefreshThisO; 
RefreshThat(); 
} 

This method is very simple, and assures that everything is 
up-to-date after it has been called. While this method works 
well for simple requesters or very small programs, once you 
add a more windows or other display areas, the program be- 
comes slow and flickery. 

On the opposite extreme, you could call the appropriate re- 
fresh functions immediately after each change is input. Al- 
though this method can eliminate unnecessary refreshing, it 
requires you to remember all of the program's interdepen- 
dencies. It also tends to create subtle bugs and make revision 
difficult at best. 

Two other problems are not adequately addressed in either 
of these methods. First, what if one refresh function depends 
on another? For example, in a 3-D modeling program, Draw- 
Polygons() might depend on CalculatePolygons(). These func- 
tions must be called in the correct order to ensure that the fi- 
nal display is completely up-to-date — if you draw objects 
before you recalculate their positions, the display will always 



remain one step behind the rest of the program. A reliable 
method must be found to ensure the correct calling sequence. 

The second problem arises when a refresh function is called 
many times quickly. For example, a user might select sever- 
al menu-based commands at once, each of which performs 
some simple operation on the project. A poorly written pro- 
gram will often refresh the display after each operation, even 
though it realty only needs to be refreshed once at the end. 
A more common example is repetition of an operation — how 
many rimes have you briefly held down some repeating key 
in a program and had to wait a long time afterwards for it to 
finish processing your keystrokes? 

These problems can be solved using various combinations 
of functions and function calls. Using flags to keep track of 
items that need refreshing can also help. No matter how care- 
fully you lay out the function calls and flags, however, you 
will still run into problems as the program gets bigger. 

A BETTER WAY 

A cleaner and more efficient method of handling refresh- 
ing is "object-oriented refreshing," which uses data struc- 
tures and lists rather than direct function calls. As you will 
see, it can conveniently solve all of the problems I've men- 
tioned using a small amount of extra code. It also helps pre- 
vent obscure bugs and makes program revision simpler. 

The basic data structure used by the system is as follows: 

struct CallNode 
{ 

struct Node Mode; 

LONG (*CallFunctionj(LONG GlobalData, LONG LocalData); 

LONG LocalData; 

}; 

((define CNTJNLIST NT_USER 

A CallNode represents a function that must be called some- 
time in the future. Think of it as a "computer agenda item." 
As you can see, it is based on Exec's standard Node structure 
and is meant to be linked into a standard Exec MinList (the 
stripped-down version of the standard List). 

When an event occurs causing a particular part of the dis- 
play to need refreshing, a CallNode is added to a List (a Call- 
List). Instead of calling the refresh function immediately, the 
call is "remembered" for later. After adding the CallNode, the 
program can continue processing other events immediately. 

A typical program will have one global CaliList in the main 
module and many small CallNodes defined in other mod- 
ules, each one representing a particular refresh function that 
might be called at some time. For example: *■ 
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static void RefreshQuickMenu(long globaldata,long localdata) 



{ 



(do all refreshing of the quick menu) 



) 



struct CallNode CallQuickMenu = { 

{0,0,0,<priority>},RefreshQulckMenu,<loeal data>); 

Then, wherever the quick menu is changed (or for some 
other reason needs refreshing), instead of immediately call- 
ing RefreshQuickMenuQ, just make this call: 

AddCallNode<&RefreshCallList,&CallQuickMenu) 

(If a particular CallList is used often, you might want to de- 
fine a macro that adds CallNodes to a specific CallList.) This 
adds the CallNode to the specified CallList. The AddCall- 
Node() function is defined as follows: 

void AddCallNodefstruct CallList M.struct CallNode "n) 

( 

rf(n->Node.ln_Type != CNTJNLIST) 

{ 

n->Node.lnJType =CNTJNLIST; 
Enqueue((struct List*)l,&n->Node); 



} 



} 



When it's time to refresh the display (probably just after all of 
Intuition's IntuiMessages are handled, but before you call 
Wait()), you simply make a single call to the function CallRem(): 

long CallRem(struct CallList 'l.long GlobalData) 

{ 

struct CallNode *n; 

long ret; 

while{n = (struct CallNode*)RemHead((struct List')!}) 

{ 

n->Node. ln_Ty pe=0; 
i1(ret=(*n->CallFunction)(GlobalData,n->LocalData)); 

return(ret); 

} 

return(O); 

1 

This function traverses the entire CallList, removing each 
CallNode as it progresses, and calls each refresh function in 
rum. (Note that CallRem(), in the source code in the accom- 
panying disk's Ford drawer, is actually a macro that uses a 
more powerful version of this function, explained later.) Each 
CallFunction must return zero if it wants the CallList pro- 
cessing to continue (the usual case) or nonzero if it wants to 
stop processing the list (if an error occurred, for example). 

By now you should have a general idea of how the system 
operates. The rule of thumb is: Save the refresh function calls 
until later, and then only call them when the user is no longer 
doing anything. 

MAPPING THE LISTS 

The use of the CallNode's ln_Type field prevents any Call- 
Node from being added to a CallList more than once. This 
helps to prevent corrupting the list, makes the caller's life 
easier and conveniently solves the problem of queueing up 
many identical or similar refresh events. You can make as 
many AddCallNodeQ calls for a particular CallNode as you 
want, but the function is only called once at the end, elimi- 
nating the need for "dirty" flags and such. 



Because EnqueueQ is used to add nodes to a CallList, the list 
always remains sorted according to priority. Because CallRemQ 
starts at the head of the list and works toward the tail, it always 
calls CallNodes with the highest priorities first to ensure that all 
refreshing is done in the correct sequence. For example, in our 
3-D modeler example, CalculatePolygons() would simply be as- 
signed a higher priority than DrawPolygonsQ and, therefore, 
would always be called before DrawPolygons(). 

As you set up your CallLists and CallNodes, keep track of 
which functions depend on which other functions, and set the 
CallNode priorities appropriately. I recommend keeping 
handy a text file that lists all the CallNodes for a given Call- 
List, their priorities, and where in your source code they are 
located. This will help you assign priorities to new CallNodes 
and will give you a good overview of which refresh functions 
are being called, in which order. 

In general, CallLists and CallNodes can simply be defined 
as global or static variables. I generally define a CallList near 
the corresponding call to CallRemQ, and put CallNodes just 

"As you set up your CallLists and 

CallNodes, keep track of which functions 

depend on which other functions, and set 

the CallNode priorities appropriately." 

below the functions they point to. In some cases, however, 
dynamically allocating CallNodes may be more appropriate. 
Just make sure you always allocate the memory with 
MEMF_CLEAR, or at least initialize the Flags field to zero be- 
fore using the CallNode. You can also have more than one 
CallRem() call for a given CallList, if you find this beneficial. 
Just remember that each call to CallRem() completely emp- 
ties the list, so the next call won't do anything unless you first 
add additional CallNodes. 

Any CallFunction (a function pointed to by a CallNode 
and called by CallRem()) may make calls to AddCallNodeQ, 
even on the CallList that's currently being traversed. This 
provides a convenient solution to another dependency prob- 
lem, in our 3-D modeler example, CalculatePolygonsQ calls 
AddCallNodeQ with the CallNode for DrawPolygons(), forc- 
ing a redraw to occur sometime after any recalculation, with- 
out either of the functions actually calling the other directly. 
in general, you should add other CallNodes with lower pri- 
ority only this way, although it is safe to add any CallNode 
if you are careful about interdependenctes. 

MORE SYSTEM FEATURES 

For flexibility, the system provides a general-purpose 
mechanism for passing parameters to the CallFunctions. The 
GlobalData variable is a LONG (you may use it as a pointer 
if you wish) that is given to CallRemQ and passed through 
to all of the functions on the CallList, as they are being called . 
This provides a convenient way to "broadcast" a piece of 
data to all the called functions. Similarly, each CallNode con- 
tains a LocalData variable that is passed to the CallFunction 
when it is activated. This is particularly useful if you dy- 

Continued on p. 63 
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InovaTools 1 version 2.0 

GUI help for both generations 

By David T. McClellan 

INOVATOOLS IS A package of 
gadgets and window functions per- 
fect for writing Intuition applications 
for AmigaDOS 1.3 and, with some 
work, 2.0. Designed to work with 
INOVAtronics' PowerWindows, 
InovaTools provides some nifty wrin- 
kles on PropGadgets, Boolean gad- 
gets, other gadget types, and menus 
and has some useful window func- 
tions. It does not appear to have been 
updated for OS 2.0, however. The 
copyright dates on the include and 
demo files were 1987/1988, and 
while the demo execu tables ran fine, I 
had fun getting the accompanying 
source working with my compilers. 
(More on that later.) 

The InovaTools routines are Intu- 
ition gadgets and utility functions, 
written to be called and used in the 
same style as the standard Commo- 
dore Intuition gadgets. Briefly, the set 
is comprised of a general purpose list 
gadget, a good file requester built on 
top of the list gadget, knob-style pro- 
portional gadgets, drag gadgets {for 
drag and drop applications), pop-up 
menus, a color-palette requester, and a 
number of window, gadget, and utili- 
ty routines. The package comes with 
header files and libraries for SAS/C 
and Manx C, libraries for linking, an 
AmigaDOS shared library for run- 
time linkage, an assembly language 
header/interface, source, and user- 
contributed link libraries for other 
languages. I tried the SAS/C (v5.10) 
and Manx libraries (I used version 
5.0a, although Inovatools comes with 
headers and libraries for v3,4b and 
3.6a as well). The most recent SAS 
compiler the package describes com- 
piling with is v4.0; perhaps this is why 
I got buggy executables using 5.10 
SAS/C. 

THE GADGETS 

Inovatools has two gadgets not seen 
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in Intuition 1.3 or 2.0 — Drag and Knob 
gadgets. Drag gadgets are Boolean 
gadgets that can be picked up and 
dragged around. Knob gadgets are an 
alternate form of the slider-style Prop- 
Gadgets we all know and love, and are 
useful for situations in which a slider 
looks wrong. They can rotate freely or 
in fixed steps and can have minimum 
and maximum angles of rotation. 

To use a DragGadget, you first lay 
out a Draglnfo data structure: 

struct Draglnfo ( 

struct Gadget 'Gadget; /* Ptr to 

BOOLGADGET */ 
SHORT LeflEdge, TopEdge, RightEdge, 
BottomEdge; 
USHORT Flags; 
SHORT XPos, YPOS; 

void {'(JpdateRoutlne) (); /' User supplied */ 
LONG DD; f Don't touch 'I 

}; 

As you can see, it looks like most 
Intuition data structures; INOVAtron- 
ics designed the InovaTools structures 
to fit easily into your programs. 

The Gadget pointer at the beginning 
of this struct points to a BOOLGAD- 
GET, which would be described else- 
where in your program and would be 
linked into your Window's gadget list. 

LeftEdge through BottomEdge 
define a bounding box for your Drag- 
Gadget; use normal numbers within 
the window's bounds to constrain the 
gadget to an area within the window. 
If you want it to be free to move any- 
where, set LeftEdge and TopEdge to 
large negative numbers, such as 
-32767, and set RightEdge and Bot- 
tomEdge to positive numbers greater 
than any possible window bound. 

The Flags field specifies further 



options for the DragGadget: 
DRAGJNWINDOW, DRAGJvlOVE- 
GADGET, and DRAGJDUTLINE. 
DRAGJNW1NDOW constrains the 
gadget to stay within its window 
whatever its bounding box is; other- 
wise it can be moved to any window. 
DRAGJvlOVEGADGET causes the 
gadget to stay where it's released 
instead of snapping back, and 
DRAG_OUTLINE instructs the draw- 
ing routine to treat color of the gad- 
get's image as transparent (for non- 
rectangular images). 

The UpdateRoutine field points to a 
call-back routine you provide, which 
is called whenever the gadget changes 
position after you hand control to the 
InovaTools' drawing routine. You can 
use it to change imagery or update 
your own data structures, 

XPos and YPOS contain the gad- 
get's position at any time, such as 
when your call-back routine is called. 

DD is private to Inovatools. 

The next step is to initialize your 
windows. Boolean gadgets, and oth- 
ers. When your message loop receives 
a GADGETDOWN message for the 
BOOLGADGET, call DragGadget() 
with a pointer to the Window contain- 
ing the DragGadget and a pointer to 
the Draglnfo struct, which should 
point to the BOOLGADGET. Drag- 
Gadget() returns when the user releas- 
es the DragGadget and inspects its 
XPos and YPOS fields at that time to 
find out where the gadget landed. The 
Which Window () routine tells your 
program which other window the 
DragGadget landed in if it didn't have 
its DRAG JNWINDOW flag set; this 
is the kind of thing you want for drag- 
and-drop applications such as drag- 
ging records to file cabinets, files to 
shredders or printers, and so on. 

The Knob gadget must be rendered 
into your Intuition screen after your 
OpenWindow() call, but otherwise has 
a similar use model. When your appli- 
cation gets a SELECTDOWN MOUSE- 
BUTTON event, it calls an InovaTools 
routine to handle the event. If the 
SELECTDOWN happened over a 
Knob, the KnobGadgetsQ routine ►- 
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processes all further input and Knob 
rendering until it receives a SELECT- 
UP and returns a pointer to the Knob. 
Otherwise it returns NULL, and your 
application can further process the 
SELECTDOWN on its own. As with 
DragGadgetsQ, you can provide an 
update routine that InovaTools calls 
each time the Knob rotates. This al- 
lows the Knob rotation to visually or 
audibly affect other parts of the appli- 
cation, such as sound volume, image 
size, or color levels. 

REQUESTERS 

InovaTools comes with a generic 
list requester, a good file requester 
built on top of the list requester, and 
a color-palette requester built with 
Knob gadgets instead of sliders. In 
addition, it provides a cross between 
requesters and menus — popup 
menus, which appear after the left- 
mouse-button event you specify. The 
generic list requester was obviously 
built prior to 2.0 Intuition. Under 1.3 
it would have been very useful, but 
now most applications prefer 2.0- 
style lists. 

The list requester has four gadgets 
that pass events to your program: List, 
ClickUp, ClickDown, and Scroll. 
These respectively cause events when 
the user selects an item in the list, 
clicks the Up or Down arrow, or slides 
the scroll bar "thumb." This requester 
also calls an application-provided 
routine to draw each list entry; this 
routine is called when the list is initial- 
ly drawn, once for each item in the 
visible list, and then each time an item 
scrolls into view. InovaTools passes 
the routine an x,y coordinate to draw, 
a pointer to the List item to draw, and 
a highlighting flag. To make things 
easy, only the first field of the List 
item struct need be a pointer to the 
next item. The List handler walks the 
singly-linked list of List items you 
provide it, rendering the relevant 
parts of the list, and scrolling when 
you request. When the the user clicks 
on the List gadget, your program is 
signaled that the user picked a list 
item. Your program can eliminate the 
list or use that choice in combination 
with other gadgets built into your 
own requester (as the file Requester 
does). As a plus, InovaTools provides 
routines to insert and delete items into 
and from the list, scroll the list up or 
down by one or more items, resize the 
list, close the list, and determine posi- 



tion information about list items. 

I've used several public domain 
pop-up menus (menus that pop-up at 
the mouse position) and the Inova- 
Tools Pop-Ups are as useful as the 
best of these. Basically, at an event 
such as a GADGETDOWN or SE- 
LECT-DOWN, your program calls the 
PopUpMenuQ routine with a standard 
Intuition menu struct, which can in- 
clude submenus. PopUpMenu() dis- 
plays one bar and side submenus 
pulled off it; it does not display or 
affect the traditional menu bar. Pop- 
UpMenuQ returns a standard menu 
selection code that your program 
decodes with the ITEMNUM and 
SUBNUM Intuition macros to get the 
user's choice (including none, if they 
deselected the menu). These are very 
easy to use and handy in applications 
in which the user often does not want 
to move the mouse up to a menu bar 
to choose an action. 

The two composite requesters — file 
and color-palette — are pretty stan- 
dard, except that the color-palette uses 
Knobs to handle RGB and HSV colors. 
The file requester supports standard 
directory and device searching, can be 
set to look for files with a certain ex- 
tension (not a complete wildcard), and 
runs under any Intuition screen. The 
color-palette requester has six knobs, 
three for RGB and three for hue, satu- 
ration, and intensity (value), and will 
also run in any Intuition screen. I 
found the file requester fairly useful, 
especially for cases where you don't 
want full wildcarding; you call it and 
it gives you back a filename. I found 
the color-palette editor less useful. 
Perhaps I'm too used to sliders, but 
the RGB knobs were more awkward 
for fractional control. 

In addition, InovaTools provides 
several handy utility routines to deal 
with gadgets, windows, and menus 
reentranth/ — to enable and set compo- 
nents of gadgets by window and ID 
rather than by pointer, to clone a win- 
dow and its gadget list, and to deal 
with menu components by ID for 
checking and enabling. Being able to 
clone a window and its gadget list is 
handy for building modeless re- 
questers and multiwindowed applica- 
tions, and the gadget-by-ID routine is 
a prerequisite for doing this. It's also a 
useful abstraction, one I prefer over 
the gadget-by-pointer method (yes, I 
do a lot of MS-Windows programming 
too). Lastly, Inovatools also has 



"flashy" window open and close rou- 
tines, which cause the opening win- 
dow to rapidly expand from a point to 
full size and collapse back at close. 

PROGRAMMING 

Inovatools comes with SAS and 
Manx linkable libraries and an Amiga- 
DOS library that you can attach at 
runtime with OpenLibraryO as a alter- 
native (the library must be installed on 
user's Amigas, in this last case.) Also 
included are beta-level libraries and 
headers for Benchmark Modula-II, 
TrueBasic, and MultiForth. Try them, 
but they're not guaranteed. I had 
problems with both the SAS and 
Manx versions, just trying to link the 
demo application. The Manx version 
first linked with some undefined 
symbols that, I eventually discovered, 
came from the floating-point library 
and were probably used by the Knob 
gadget; the routines were called by the 
Inovatools library. The SAS version 
linked right away, but crashed off and 
on in the cloned-window and Drag- 
gadget routines. The file requester, 
Knob gadget, and list requester all 
worked fine, as did the executables of 
the supplied demos. The problem 
turned out to be some pointer and 
structure offsets that the routines 
weren't expecting; I'm still tuning it 
for DragGadgets. Lists and Knobs 
appear to work satisfactorily, and 
pop-up menus as well. 

The manual is pretty good for a 
developer-oriented package like this; 
each routine and data structure is well 
described, and source code for all the 
routines is included. 

For two reasons, I can't wholeheart- 
edly recommend this package. I like 
what the author has done, and the 
style and docs are good. But, some of 
the features are outdated (the list 
requester for one), and the routines 
don't work right out of the box with 
all compilers. You have to rune and 
tweak InovaTools' and your compiler 
options. InovaTools is useful (more so 
for 1.3 Intuition applications), yes, but 
you must "tinker under the hood" to 
the get full effect. ■ 

InovaTools 1 version 2.0 

INOVAtronics 

8499 Greenville Ave., Suite 209B 

Dallas, TX 75231 

214/340-4991 

$99.95 

No special requirements. 



^J 



30 March! April imi 



~ 




TNT 



Technical News and Tools from the Amiga Community. 

Compiled by Linda Barrett Laflamme 



Storm Watch 



Plugging into your A500 or A2000 processor socket, Storm- 
bringer sports 68030 and 68882 chips and up to eight 
megabytes of RAM. The Stormbringer accelerator is available 
in several speeds; the 16 MHz board is $1099, the 24 MHz 
model is $1199, and the 30 MHz unit is $1549. The two top- 
of-the-line models are a $2349 board with a 50 MHz 030 and 
a 60 MHz 68882, and Stormbringer 55sync ($2599) with a syn- 
chronous 55 MHz processor and coprocessor, which promis- 



es to run 35% faster than the standard 50 MHz version. (Prices 
include 4MB ZIP-RAM.) The board's disable switch comes in 
handy for finicky programs. Also included in the package is 
software that activates burst mode, caches, and loads Kickstart 
into RAM. Stormbringer's German developer Memphis Com- 
puter Products GmbH does not as yet have a U.S. distributor, 
but you can contact the company directly at Gartenstr. 11, 
6365 Rodheim v.d.Hohe, 0049-06007/7789,8690. 
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A New Team of Old Friends 



What do you do when you 
have two popular products 
that both require the CPU 
socket? Combine them into 
an all-in-one solution is ICD's 
answer. The AdSpeed/IDE 
pairs AdSpeed, ICD's 14 
MHz accelerator for the A500 
and A2000, with AdIDE, the 
company's A500/A2000 in- 
terface for IDE hard drives. 
The benefits to you are a 



68000 CPU that runs at twice 
the normal clock rate, 32K of 
high-speed static RAM for a 
16K cache and 16K of cache 
tags, a 7 MHz mode for com- 
patibility (selectable via the 
accompanying software or an 
optional hardware switch), 
and an autoconfig, auto-boot- 
ing interface for IDE hard 
drives. The combo is available 
in three packages: the Ad- 



C Scoop 



If you're struggling to learn the basics of SAS/C, consid- 
er consulting Observations, SAS Institute's new technical 
journal. Published quarterly in a joint effort of the SAS tech- 
nical support and documentation development depart- 
ments, Observations promises to cover technical applications 
and techniques for the company's programming tools and 
operating systems interfaces, as well as statistics, graphics, 
and display software. Issues are $15 apiece or $49 for a year's 
subscription. For more information, contact SAS Institute's 
book sales department at SAS Campus Dr., Cary, NC 27513, 
919/677-8000. 



Speed /IDE-40 for installing 
an IDE drive in an A2000, the 
AdSpeed /IDE-44 Kit for in- 
stalling a 2.5-inch IDE drive 
in an A500, and the Ad- 
Speed /IDE^O Kit for replac- 
ing an ASOO's internal floppy 
with a hard drive. For prices, 
contact ICD Inc., 1220 Rock 
St., Rockford, IL 61101, 
815/968-2228. 
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Organized and Backed-Up 



Tired of clicking to the sev- 
enth level of your hard 
drive's directories just to run 
one program? 

Display Systems Interna- 
tional's Hard Disk Organiz- 
er ($44.95) lets you run appli- 
cations and scripts with only 



one click. Each of the unlim- 
ited number of buttons can 
be programmed with up to 
eight AmigaDOS commands, 
so you can include any as- 
signs, directory changes, and 
so on necessary to run your 
applications. To help you 



group your applications by 
type and quickly identify 
them, each button can be as- 
signed one of ten colors. Di- 
rect your inquiries to Display 
Systems International, 147 
West Main St., Dayton, PA 
Continued on p. 34 
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At last, a development standard for 
the next generation of Amiga 
Graphics and Video Software. 

For the ultimate in high-resolution 8 to 32 bit 
graphics and video applications, Digital 
Micronics and Progressive Peripherals & Software 
jointly developed a communications interface 
for the Texas Instruments 340x0 high 
performance graphics processor family and the 
Amiga's 680x0. 

Applications developed with SAGE will run on 
DMI's Resolver™ Graphics Board. PP&S's 
Rambrandt™ Video/Graphics board, or any 
other video/graphics board which supports the 
SAGE instruction set - NTSC and PAL. systems. 

Focus Your Creativity, and Reach New 
Markets. 

With SAGE it's easy to quickly port existing 
Amiga software, or develop new high- 
performance applications. SAGE's software 
system provides a simple, efficient way to send 
instructions and data back and forth between 
the Amiga and SAGE-com pliant graphics 
board(s). SAGE is based on Texas Instrument's 
TIGA interface specification, the leading 
graphics standard for PC-compatible systems. 
SAGE goes beyond this specification by 
incorporating many Amiga specific 
enhancements. 

The Right Tool for the Job. 

The core SAGE library consists of over 120 
optimized, high-performance functions. 
Geometric drawing functions include: line, oval, 
ovalarc, piearc, point, polygon, polyline, 
rect(angle), seed, and more. Style functions 
include: draw, styled, pen, pat(ter)npen, fill, 
patnfill, frame, patnframe, and more. Core 
system functions include: init_cursor, 
set_cursor_xy, set_ppop, setjransp, and many 
more. 
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SAGE functions provide easy access to the 
many powerful graphic capabilities of the Tl 
340x0 processors. There are functions for setting 
transparency, defining how pixels are 
combined, bit-blitting, text definition and 
display, hardware clipping, page-flipping 
animation, and many more. SAGE functions 
provide the resources which graphic and video 
application developers need the most, from 
low-level to high-level graphics and video 
processes. The SAGE library documentation 
thoroughly details the use of all SAGE functions. 

Power for Present and Future 
Applications. 

SAGE insures expandability by allowing you to 
create your own custom libraries. 

The functions provided are only the beginr 
you can create your own executable functions 
to streamline and optimize your software. 
Future updates planned for the SAGE library 
include JPEG decompression for real-time video 
applications, and enhanced 3-D functions 
libraries. 

SAGE extensions for DMI's Resolver™ take full 
advantage of the Resolver™'s ultra high- 
resolution 1280 x 1024 double buffered display 
and onboard Tl 34010 60MHz processor. 

PP&S provides additional SAGE libraries for use 
with Rambrandt™. With these libraries, multiple 
board/multiple monitor systems can be 
configured in a virtual desktop system, to 
distribute a single image over multiple monitors. 
Other Rambrandt™ Library functions support 
parallel processing, alpha channel functions for 
video overlay, transitions between buffers ("A/B 
rolls"), fast image loading, multiple 256-color 
images on the same screen, and 3-D 
graphics/TI 34082 coprocessor functions for 3-D 
specific modeling and rendering. 

Many respected, successful Amiga developed 
have pledged their support to SAGE. For 
information on how to receive the SAGE 
development system, contact DMI or PP&S. 
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Standard Amiga 
Graphic Extension 



PROGRiXriVt P€RIPH€RRL/'&/OFTUJRR€ 

Attn: Steve Spring 
~ 464 Kalamath Street 
Denver, CO 80204-5020 
Tel: (303) 825-4144 
Fax: (303) 893-6938 




DIGITAL MICRONICS, INC, 

Attn: Dean Agar 
5674-P El Camino Real 
Carlsbad, CA 92008-7130 
Tel: (619) 931-8554 
Fax:(619)931-8516 
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16222, 814/257-8210. 

For more power and flexi- 
bility, consider Directory 
Opus ($59.95). The program 
offers configurable menus, 
user buttons (84), and vol- 
ume/device-name buttons 
(24); the ability to load or edit 
a config file, on-line help, un- 
limited directory history, a 
full directory tree, DOS error 
code help, ARexx support, 
CPU-usage and memory 
monitors, and a date/time 
display. Directory Opus 
plays ANIMs, ANIMBrush- 
es, 8SVX sounds, raw data 
sounds, and SoundTracker 
files; shows brushes, pic- 
tures, and icons; displays 
fonts and Hex, and runs exe- 
cutables (with user-definable 
parameters] and CanDo 
decks; all you do is double 
click on the file's name. For 
more information, contact 
INOVAtronics, 8499 Green- 
ville Ave. #309B, Dallas, TX 
75231, 214/340-4991. 
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Simply elicit <o execute applications and scripts (ram Hard Disk Organizer. 



Once you have your hard 
disk efficiently organized, 
back it up! To help, Central 
Coast Software recently up- 
graded its popular back-up 
utility. Quarterback 5.0 
boasts such new features as 
integrated streaming tape 
backup, compression, op- 
tional password protection 
and encryption, ARexx and 
2.0 support, and additional 



backup and restore options. 
The company also promises 
performance, the user inter- 
face, and file-selection versa- 
tility were improved. Plus, 
you can now backup or re- 
store to up to four floppy 
drives. For $75, Quarterback 
5.0 is available from Central 
Coast Software, PO Box 
164287, Austin, TX 78716, 
512/328-6650. 



Development Watchdog 

Designed for the Amiga and composed of 11 command-line 
utilities, QVCS (Quma Version Control System) automatical- 
ly tracks your source and binary files through development, 
saving the differences between various revisions in a single 
file. The lock-file protection lets you use multitasking QVCS 
on networked systems, and for multi-developer projects 
QVCS will coordinate accesses and updates to modules that 
are shared by several programmers. 

Need to backtrack? The program retrieves previous file ver- 
sions and supports journaling. With this feature on, QVCS 
logs all file changes into a protected journal file, supplying the 
name of the file modified, the time and date, the name of the 
person changing the file, and a synopsis of the command used. 

Other handy features include an editable message file that 
defines the message strings used by QVCS utilities, a file-com- 
pare utility for both binary and ASCII files, accidental dele- 
tion protection, and the ability to automatically expand such 
keywords as $Revision$, $Author$, $Date$, $Log$, $Version$, 
and $VER$. 

To acquire QVCS you'll need $99, to run it, one meg of 
RAM. For all the details, contact Quma Software, 20 Warren 
Manor Court, Cockeysville, MD 21030, 410/666-5922. 



What's on the Schedule? 



If you or your company 
has a hot new product on the 
way, tell us about it, and 



we'll tell the readers. Send 
your press releases and an- 
nouncements to The Amiga- 



World Tech Journal, 80 Elm St., 
Peterborough, NH 03458, or 
llaflamme on BIX. ■ 
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Tech Journal 
Disk 
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You'll find source code and exe- 
cutables for the article examples, 
including: 



Revision Control System— a program 
development tracker 

Animation Routines— From simple to 

hierarchical motion 
SetRemind — A reminder utility in ARexx 




This nonbootable disk is divided into two main directories, 
Articles and Applications. Articles is organized into subdirec- 
tories containing source and executable for all routines and 
programs discussed in this issue's articles. Rather than con- 
dense article titles into cryptic icon names, we named the 
subdirectories after their associated authors. So, if you want 
the listing for "101 Methods of Bubble Sorting in BASIC," by 
Chuck Nicholas, just look for Nicholas, not 101MOBSIB. The 
remainder of the disk, Applications, is composed of direc- 
tories containing various programs we thought you'd find 
helpful. Keep your copies of Arc, Lharc, and Zoo handy; 
space constraints may have forced us to compress a few files. 



Unless otherwise noted in their documentation, the sup- 
plied files are freely distributable. Read the fine print care- 
fully, and do not under any circumstances resell them. Do be 
polite and appreciative: Send the authors shareware contri- 
butions if they request it and you like their programs. 

Before you rush to your Amiga and pop your disk in, make 
a copy and store the original in a safe place. Listings provid- 
ed on-disk are a boon until the disk gets corrupted. Please take 
a minute now to save yourself hours of frustration later. 

If your disk is defective, return to AmigaWorld Tech Jour- 
nal Disk, Special Products, 80 Elm St., Peterborough, NH 
03458 for a replacement. 
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Programming Motion: 
Animation Elements 



By Paul Miller 



ONE OF THE many unique features of the Amiga is its 
built-in set of low-level graphics and animation routines. The 
graphics library has a very powerful animation system that 
allows you to set up your animated graphics and then forget 
about them, at least until something important happens (such 
as, say, your animated super-hero gets hit by a MegaKill 
Bomb or falls into the Pit of Doom). The animation system 
keeps track of the movements and drawing of all your ani- 
mated objects, allowing you, the programmer, to concentrate 
on collision and other program mechanics. 

Several levels of animation are supported, each built upon 
different types of Graphic Elements (GELs). The more com- 
plex Graphic Elements, in turn, are built upon previous GELs 
in a hierarchical manner. 

Simple Sprites are not GELs, but form the lowest level of 
moveable graphics support. They are the fastest and most ef- 
ficient graphics objects, but are limited in their resolution and 
restricted to eight colors. They are drawn directly by the 
graphics hardware, overlaying normal bitmap graphics, and 
must be controlled by the program. The mouse pointer is a 
hardware sprite. 

Virtual Sprites (VSprites) are the simplest GELs. They are 
based on simple sprites, but allow the system to reuse sprites 
as needed. More than eight are allowed on the screen at one 
time, with certain position restrictions. Virtual Sprites also 
contain support for software collision detection, and are 
drawn for you by the GEL system. 

Blitter Objects (BOBs) are based on the VSprite, but are 
handled by the Blitter and can be of any size and number 
of colors with respect to the background graphics. Since 
they are drawn directly into the playfield, they are slower 
than VSprites. They can automatically handle saving and 
restoring of the background, double-buffering, and soft- 
ware collision detection. They form the basis of animation 
components. 

Animation Components (AnimComps) are combined to 
make up a complete animation object, each pa rt representing 
one frame of one piece of the entire object. Each AnimComp 
is attached to a BOB which contains that frame's imagery. 

Animation Objects (AnimObs) are complete objects han- 
dled directly by the animation system. They can be com- 
posed of many linked AnimComps and support several 
types of animation. 

THE HARDWARE SPRITE SYSTEM 

Simple Sprites are drawn directly by the display hardware 
and are overlayed on playfield (bit-mapped) graphics. (They 
can be coaxed into being rendered under certain playfield 
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planes, but in common practice this is not done.) Sprites do 
not, however, directly affect the data which makes up the 
playfield graphics. They are also rendered with respect to 
the current ViewPort, not the playfield graphics, so when 
you move your screen up and down, the sprites do not move 
with it. (You can observe this affect if you have the public do- 
main communications program JRCOMM. The blinking cur- 
sor is a simple sprite. Try dragging the JRCOMM screen up 
and down or even switching screens, and you'll see that the 
cursor does not move). 

Simple sprites are always 16 pixels wide and can be any 
height. Their dimensions are always in low-resolution pixels; 
they appear the same size in any display mode (except 31 KHz 
display modes where they may appear vertically squashed 
or horizontally stretched). 

Each sprite can have only four colors, and the colors for all 
eight sprites are located in color registers 16 through 31. 
Sprites 1 and 2 share registers 16 through 19, sprites 3 and 4 
share registers 20 through 23, sprites 5 and 6 share 24 through 
27, and sprites 7 and 8 share 28 through 31. The lowest regis- 
ter number per sprite pair (color for that sprite) is not used 
by the sprite hardware, so sprites can really be only three col- 
ors plus a transparent color where the background shows 
through. Keep in mind that sprite color registers are shared 
by the playfield if the ViewPort is five or more planes deep. 

There are only eight simple hardware sprites available, 
and typically one is always being used by the system (if 
you're not sure which one this is, try moving your mouse a 
bit and it may come to you). Two sprites can be combined to 
create an "attached" sprite with 16 colors, but this is beyond 
the scope of this article. (Watch for more details in an up- 
coming issue.) 

Simple sprites are based on the SimpleSprite structure: 

struct SlmpleSprlle 



t 



UWORD 'posctldata; 
UWORD height; 
UWORD x, y; 
UWORD num; 

}; 

Simple sprites are handled with four simple functions 
found in the graphics library. The GetSprite() function allo- 
cates a new sprite from the sprite system. 

sprltenum = GetSpritefsprilo, num); 

Here, sprite is a pointer to a SimpleSprite structure, and 
num is the sprite number (0-7) requested. If num is -1, Get- 



~ 



Harness the power of the Amiga's built-in Sprites, VSprites, 
BOBs, AnimComps, and AnimObs. 






~ 



Sprite() will attempt to allocate the first available sprite. 
Spritenum is the number (0-7) of the allocated sprite, if one 
was available, or -1 if no sprites were available. 

struct SimpleSprite sprite; 
WORD spritenum; 

/* set up the initial sprite Information */ 
sprlte.Helght = 8; 
sprite.x - 0; 
sprite.y a 0; 

spritenum = GetSprite(&sprite, -1); /' any sprite 7 

It (spritenum = -1) 

{ 

f exit V 

} 

The ChangeSpriteO function is used to change the appear- 
ance of a sprite. 

ChangeSprite(vp, sprite, data); 

Vp is a pointer to the ViewPort that the sprite is based in, 
or to NULL if the sprite is in the current View. Sprite is a 
pointer to a SimpleSprite allocated with GetSprite(). Data is 
a pointer to a block of memory describing the new sprite im- 
agery, as well as some additional control information. The 
format of this data is as follows, and it must reside in chip 
memory: 

struct spritelmage { 

UWORD posctl[2]; 

UWORD data[height][2]; 

UWORD reserved[2]; 
}: 

/' sprite data for an 8x8 checkered square */ 
UWORD chip s^datafj = { 

0, 0, P position/control 7 

Ox F0OO, 0X0FQ0, 

OxFOOO, OX0FO0, 

OxFOOO, OxOFOO, 

OxFOOO, OxOFOO, 

OxOFOO, OxFOOO, 

OxOFOO, OxFOOO, 

OxOFOO, OxFOOO, 

OxOFOO, OxFOOO, 

0, r reserved */ 

}; 



struct SimpleSprite sprite; 
ChangeSprltefNULL, &sprlte, s_data); 

The MoveSprite() function changes a sprite's position. 

MoveSprite(vp, sprite, x, y); 

Vp is a pointer to the ViewPort that the sprite is based in, 
or NULL if the sprite is in the current View. Sprite is a point- 
er to a SimpleSprite structure allocated with GetSprite(). X 
and y are the coordinates where the sprite should be moved 
to, in ViewPort pixels. (If vp is NULL, the coordinates are as- 
sumed to be in low-resolution pixels). Pixel precision for 
sprites is always low resolution, however, even if your View- 
Port is hi-res. 

struct SimpleSprite sprite; 

MoveSprite(NULL, isprlte, 160, 100); 

When you're finished with the sprite, use the FreeSprite() 
function to release it. 

FreeSprite(sprItenum); 
Spritenum is the sprite number to free. 

struct SimpleSprite sprite; 
WORD spritenum; 

spritenum = GetSprite(& sprite, -1); 

/" error checking - use sprite 7 

FreeSprite(spritenum); 

To use sprites in an Intuition screen, be sure to set the 
SPRITES flag when opening the screen. All sprites can be 
turned on and off at once with the macros ON_SPRilfc and 
OFF_SPRITE, defined in gfxmacros.h. These actually enable 
and disabled sprite DMA at the hardware level. 

See the program Sprite on the disk for complete example 
code on using SimpleSprites. 

VIRTUAL SPRITES 

Virtual sprites are the simplest form of GELs, and are han- 
dled by the animation system. The animation system converts 
a virtual sprite into a simple sprite for rendering, so virtual 
sprites have the same restrictions as simple sprites, except 
that there can be more than eight virtual sprites, as long as 
there are no more than eight on a single scanline. Virtual 
sprites also have built-in collision detection and handling, i 
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and can be extended to include user information for control 
purposes. 

Virtual sprites are described by the VSprite structure: 

struct VSprite { 

struct VSprite 'NextVSprite; 
struct VSprite 'PrevVSprlte; 
struct VSprite 'DrawPath; 
struct VSprite 'ClearPath; 
WORD OldY, OldX; 
WORD Flags; 
WORD Y, X; 
WORD Height; 
WORD Width; 
WORD Depth; 
WORD MeMask; 
WORD HitMask; 
WORD "ImageData; 
WORD 'BorderLlne; 
WORD -CollMask; 
WORD 'SprColors; 
struct Bob *VSBob; 
BYTE PlanePIck; 
BYTE PlaneOnOff; 
VUserStuff VuserExt; 

); 

This structure contains all necessary hooks for linking the 
VSprite into the graphic element list, collision handling, and 
AnimComp control when linked to a BOB. 

The width of a VSprite is in WORDs, and for a true VSprite 
(not linked to a BOB), it is always 1. The depth is always 2 
(because sprites can have only four colors). These fields can 
be different when using BOBs. The position of a VSprite is set 
by changing the X and Y fields of the VSprite structure. 



vsprite. Width = 1; 


/" always for true VSprites V 


vsprite. Depth = 2; 


r ditto */ 


vsprtte.X = 0; 




vsprlte.Y = 0; 





Because this is a true VSprite (not being used as a BOB), the 
VSPRITE flag must be set in the VSprite's Flags field. 

vsprlte.Flsgs = VSPRITE; 

The ImageData pointer points to the sprite imagery, which 
must reside in chip memory. This data is organized the same 
way as for SimpleSprite imagery, without the extra control 
information. Each line of data is described by two 16-bit 
WORDs, so the entire VSprite image is stored in Height*2 
WORDs. The first WORD contains the least-significant bit of 
the color select mask for each pixel, and the second WORD 
contains the most significant bit. These bits are combined to 
form a binary color select mask as described below: 

00 — "transparent" color (unused register) 

01 — VSprite's first color 

10 — second color 

11 —third color 

/• data for a checkered square 8x8 pixels */ 
UWORD vs dataQ = { 

OxFOOO, OxOFOO, 

OxFOOO, OxOFOO, 



OxFOOO, OxOFOO, 
OxFOOO, OxOFOO, 
OxOFOO, OxFOOO, 
OxOFOO, OxFOOO, 
OxOFOO, OxFOOO, 
OxOFOO, OxFOOO, 

}; 

vsprite.Height = 8; 
vsprlte.lmageData = vs data; 

Each VSprite can have its own set of three colors, which 
will be used when the VSprite is drawn. In this case, the 
SprColors field points to an array of three 16-bit color 
values. 

UWORD vs colorsrj = {OxOFOO, OxOFFF, OxOOOF); 
/' red, white, and blue V 

vsprlte.SprColors = vs colors; 

If SprColors is NULL, the VSprite will be rendered in the 
colors already residing in the playfield's colormap at the reg- 
isters used by the VSprite. Because the system will dynami- 
cally allocate a SimpleSprite for the VSprite when it is drawn, 
you have no way of knowing which colors will be used to 
render your VSprite, so it is best to specify a color array for 
each of your VSprites. 

Note that the colors used to draw your VSprite will be 
loaded into the display's color table when the VSprite is 
drawn, so your background playfield may change colors if 
parts of it are drawn using the same registers. To avoid this 
problem, you can use a four-bitplane display, which only 
uses the lower 16 colors, avoiding the colors used by the 
sprite system. Or, you can avoid using colors 17-19, 21-23, 
25-27, and 29-31 to draw your playfield graphics. If two 
VSprites have the same colors, you can assign both SprCol- 
ors fields to the same color array, and the system will at- 
tempt to pair the two VSprites, thus helping to avoid color 
conflicts. 

USING VSPRITES 

VSprites are added to the current display's GEL list (which 
resides inside the display's RastPort) with the AddVSprite() 
function. 

struct RastPort rastport; 
struct VSprite vsprite; 

AddVSprite(&vsprite, &rastport); 

The VSprite must be initialized correctly before it can be 
added to the GEL list or unpredictable and potentially ugly 
things may happen to your display. 

To remove a VSprite from the display, use the RemV- 
SpriteQ function. 

RemVSprltef&vsprlte); 

Make sure that the VSprite has been added with AddV- 
Sprite() before attempting to remove it. 

Once all the VSprites have been added, they must be sort- 
ed so the system can assign simple sprites in the proper or- 
der. Use the SorrGList() function for this. 

SortGLIstf&rastport); 

To instruct the system to actually render the VSprites, call 
the DrawGListQ function. 
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struct Viewport viewport; 
struct RastPort rastport; 

DrawGList(&rastport, &viewport); 

You must use SortGList() before calling DrawGList() when 
VSprite positions have changed, as the sorting step is essen- 
tial for proper allocation of simple sprites. 

Now you must tell the system that display imagery has 
changed. If you're using Intuition, call MakeScreen() and Re- 
thinkDisplay(). If you're handling the display yourself, per- 
form a MrgCopQ and LoadViewQ. Do a WaitTOF() first to 
synchronize the display of the VSprites with the vertical- 
blanking period. MrgCopO, however, can be quite slow (rel- 
atively speaking), so it may be more appropriate to put your 
WaitTOFQ just before the LoadViewQ. The example used 
here is based on information from the ROM Kernel manuals, 
so it remains intact for "correctness" sake. 

f under intuition V 
struct Screen "screen; 

SortGList(&sereen->RastPort); 

DrawGList(&sereen->RastPort, &screen->VlewPort); 

MakeScreen(screen); 

RethinkDisplayO; f calls WaitTOF() for you V 



/* custom display V 
struct View view; 
struct Viewport viewport; 
struct RastPort rastport; 

SortGList(&rastport); 

DrawGList(&rastport, &viewport); 

WaitTOFO; 

MrgCop(&view); 

LoadVlewf&view); 

VSprites are always drawn in sorted order along the Y and 
then the X axis, starting at the upper-left corner of the screen. 
Later VSprites will overlap VSprites drawn above and to the 
left of them. 

Between calls to DrawGList(), the position of a VSprite can 
be changed dynamically by altering the X and Y fields, and 
the imagery can be changed by pointing the ImageData field 
to new image data. 

Before any of these GEL functions may be used, the GELs 
system must first be set up properly (this must be done for 
each RastPort that GELs will be used in). To do this, you 
need to properly initialize a Gelslnfo structure and several 
areas of memory used by the GELs system, as well as two 
dummy VSprites. Then InitGelsQ must be called with this 
information. 

struct Gelslnfo gelsinfo = {0}; 
struct VSprite vs_head = (0); 
struct VSprite vs_tail = {0}; 
struct RastPort rastport; 

f initialize Gelslnfo data */ 
lnltGels(&vs_head, &vs_tail, figelsinfo); 

See the VSprite program in the Miller drawer on the disk 
for complete VSprite example code, as well as a generic GEL 



system initialization routine, to be used before any of the 
GEL functions can take place. 

WHAT ABOUT BOBS? 

BOBs (Blitter OBjects) form a more powerful animation 
subsystem that can be used to create animated objects capa- 
ble of complex hierarchical movement. 

Although BOBs have VSprites at their cores, they are much 
more flexible. A BOB can be as large as you like, memory 
permitting, and can have as many colors as the play field. 
Think of it as essentially a standard BitMap graphic with 
GEL information. 

Because BOBs are actually drawn into the display play- 
field, they are somewhat slower than VSprites, and extra pre- 
cautions must be taken to avoid trashing background im- 
agery. These precautions are, however, handled mercifully by 
the animation system. 

With a few exceptions, BOBs share all the standard GEL in- 
formation with VSprites (this is logical, since a BOB is essen- 
tially an extended VSprite). 

The location of a BOB (X and Y) is in pixel coordinates 
with the same resolution as the playfield. The size of a BOB 
is also in background pixels, and the width may be more 
than one WORD. The Flags field does not contain the 
VSPRITE flag, and the SAVEBACK and OVERLAY flags may 
be used for additional features. The depth of a BOB may be 
as deep as the background playfield. BOB image data is in a 
different format than VSprites, but is still pointed to Image- 
Data. SprColors should be NULL, and the VSBob field points 
to a Bob structure. 

struct Bob { 
WORD Flags; 
WORD 'SaveBuffer; 
WORD 'Images hadow; 
struct Bob 'Before; 
struct Bob 'After; 
struct VSprite 'BobVSprfte; 
struct AnimComp 'BobComp; 
struct DBuf Packet 'DBuffer; 
BUserStuff BUserExt; 

}; 

struct VSprite vsprite = {0}; 
struct Bob bob ■ {0); 
UWORD bobjmagerj = { 

/' BOB image data, organized in planes like a BitMap. 

in this case, there will be 2*32 (64) WORDS per plane, 

times 5 planes, so there will be 640 bytes of Image 

data total 7 
}; 



vsprite. X = 0; 
vsprite.Y a 0; 
vsprite.Width = 2; 
vsprlte.Height = 32; 
vsprite. Depth = 5; 
vsprite.Flags = NULL; 
vsprtte.SprColors = NULL; 
vsprite. ImageData = bob image 
vsprite. VSBob = &bob; 



/• up to 32 pixels wide '/ 

/* up to 32 colors In BOB 7 
.'" no special features 7 



The BOB itself must be linked to the VSprite as well, so the 
Bob VSprite field points to the VSprite. *■ 
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bob.BobVSprtte = Svsprlte; 

To have the BOB automatically save and restore the 
background as it moves (so the entire background need 
not be redrawn each frame), set the SAVEBACK flag in the 
Flags field of the VSprite, and allocate a block of chip 
memory large enough to store the area covered by the 
BOB. The memory must be able to store as many planes 
as there are in the playfield, regardless of the number of 
planes in the BOB. This pointer gets stored in the BOB's 
SaveBuffer field. 

struct VSprite vsprlte; 

struct Bob bob; 

struct RastPort rastport; 

vsprlte. Flags 1= SAVEBACK; 

long size = (fong)slzeof(UWORD) * vsprite.Width • vsprlte. Height * 

rastport.BitMap.DepIh; 

bob.SavcBuffer = (WORD *)AllocMem(slze, MEMF_CHIP); 

By default, the entire rectangle of image data is used to re- 
place the playfield imagery. To draw the BOB imagery 
through a mask (for a cookie-cut effect, which is the most 
common technique), set the OVERLAY bit in the VSprite's 
Flags field and point the BOB's ImageShadow field to a one- 
plane shadow mask (most-commonly the logical OR of all of 
the planes of the image) which is the same size as the BOB. 
If collision detection is being used, this can point to the 
VSprite's CollMask (or vice-versa). This data must reside in 
chip memory. 

vsprlte. Rags 1= OVERLAY; 

bob.lmageShadow = (WORD *)AllocMem((long)slzeof(UWORD) * 
vsprtte.Width * vsprlte. Height, MEMF_CHIP); 

or, if the VSprite's CollMask has been initialise 
bob.lmageShadow = bob,BobVSprlte->CollMask; 

If you do not want the system to bother with saving and 
restoring the background imagery, set the SAVEBOB flag in 
the BOB's Flags field. If the BOB is part of an AnimComp, set 
the BOBISCOMP flag. Do not confuse the VSprite's Flags 
field and the BOB's Flags field. VSPRITE, SAVEBACK, and 
OVERLAY are VSprite flags. SAVEBOB and BOBISCOMP 
are BOB flags. 

Several options are available for selecting colors for BOBs, 
making possible nifty special effects through a clever ma- 
nipulation of the VSprite PlaneOnOff and PlanePick fields. 

Typically, the Depth field provides all the information 
necessary. If your display and BOB are both five planes 
deep, and your desired color palettes for both match, you've 
got nothing to worry about. Your BOB can have fewer 
planes of data than the playfield, however, and by default, 
only the number of planes provided are copied into the dis- 
play. 

You can specify selectively which display planes your BOB 
imagery is copied into by setting bits in the PlanePick field 
(this is typically OxFF, enabling all planes). If you have a two- 
plane BOB and a five-plane display, and you want plane zero 
of the BOB in plane zero of the display and plane one of the 
BOB in plane two of the display, set the first (bit 0) and third 
(bit 2) bits in PlanePick. 



bob. Depth = 2; 

bob.PlanePiek = 0x05; r bit I bit 2 -> 00000101 7 

What do you do with the unused planes in the back- 
ground? This is handled by the PlaneOnOff field. If there is 
a bit set in this field, Is are copied into the plane specified by 
this bit. If this bit is clear, Os are copied. If the OVERLAY bit 
is set and the ImageShadow mask is used in drawing the 
BOB, bits in the destination plane are set or cleared where the 
mask exists. If the OVERLAY bit is clear, the entire rectangle 
is set or cleared for that plane. 

As an overview, image data is blitted into planes that have 
a bit set in the PlanePick field, Is or 0s are set in planes that 
have bits set or cleared in the PlaneOnOff field. 

If collision masks have been allocated for the VSprite, and 
the BOB's ImageShadow points to the VSprite's CollMask 
field, the system can automatically generate the image shad- 
ow mask for you with a call to InitMasks(). 

vsprfte.CollMask = (UWORD ■)AllocMem«long)slzeof(UWORD) * 
vsprite.Width • vsprite.Height, MEMF.CHIP); 
bob.lmageShadow = vsprfte.CollMask; 

In itMa sks (& vs pri I e) ; 

DOUBLE-BUFFERING 

Double-buffering, by enabling essentially two drawing ar- 
eas, is used to minimize flickering caused when graphics are 
being drawn into the display. While one is being displayed, 
the other is being drawn into, then they swap and the pro- 
cess continues. This way, you don't see complex objects be- 
ing rendered, just the results, and you are greeted with 
smoother animation. 

If BOBs are to be used in a double-buffered display, a 
DBufPacket extension structure must be initialized and as- 
signed to the BOB's DBuffer field. 

struct DBufPacket { 
WORD BufY, BufX; 
struct VSprite 'BufPath; 
WORD 'BufBufter; 

1; 

The BufBuffer field of the DBufPacket points to an area of 
chip memory large enough to hold the region of background 
imagery covered by the BOB (the same size as the BOB's 
SaveBuffer area). 

struct Bob bob; 

struct DBufPacket dbufpacket = {0}; 

long size; 

bob. DBuffer - &dbufpacket; 

size = (long)slzeof(UWORD) * bob.BobVSprlte->Width * 
bob.BobVSprite->Height * bob.BobVSprlte->Depth; 
dbufpacket.BufBuffer = (WORD *)AllocMem(slze, MEMF_CHIP); 

USING BOBS 

Unlike VSprites, the drawing order of BOBs can be spec- 
ified by chaining BOB Before and After pointers. To draw 
bobl after bob2, bobl's Before pointer points to bob2, and 
bob2's After pointer points to bobl. If this seems confusing, 
it is! But due to historical reasons it's the way you have to 
doit. 

Here it is again: 
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struct Bob bobl; 
struct Bob bob2: 

f link the BOBs so bobl is drawn before bob2 */ 

/' incidentally, bob2 is drawn after bobl V 

bobl .Before = &bob2; 

bobl .After = NULL; 

bob2.Before=NULL; 

bob2.After = &bob1 ; 

To add a BOB to the current GEL list, use the AddBobQ 
function: 

struct Bob bob; 

struct RastPort rastport; 

AddBob(&bob, &rastport); 

When finished with the BOB, remove it with RemBob(): 

RemBob(&bob); 

Actually, RemBob{) is a macro that sets the BOBSAWAY 
flag in the BOB, and the BOB is removed by the system dur- 
ing the next call to DrawGList(). To remove the BOB imme- 
diately and unlink it from the GEL list, use RemIBob(). 

RemlBob(&bob, Srastport, ^viewport); 

You must call DrawGListQ again after using RemlBobQ to 
refresh any BOBs that were erased when the BOB was re- 
moved. As with VSprites, SortGList() and DrawGListQ must 
be called to display the BOBs, and after changes to the BOB 
position or imagery. If you are managing the display yourself, 
but are not dealing with any true VSprites, just BOBs, you can 
safely omit the calls to MrgCopQ and LoadView(), because no 
special Copper instructions need be generated for BOBs. 

Between calls to SortGList() and DrawGList(), you can 
change dvnamicallj the position of the BOB by modifying 
the X and Y fields of the BOB's VSprite structure; the imagery 
by changing the ImageData pointer (if you're using the 
BOB's ImageShadow, be sure to call InitMasksQ on the BOB 
to update the mask); and the drawing priorities by modify- 
ing the Before and After pointers. The PlanePick and Pla- 
neOnOff fields can also be changed on the fly to modify the 
BOB's colors, 

COLLISION HANDLING 

The GELs system offers two types of collision detection: 
GEL-to-GEL and GEL- to-bound a ry. To enable collision han- 
dling, you must allocate the collision-handler table and assign 
it to the Gelslnfo CollHandler field. This table is really an ar- 
ray of 16 pointers to collision-handler functions. One handler 
is used for GEL-to-boundary hits, and the other 15 are used 
for GEL-to-GEL hits. The actual function called is based on 
the colliding GELs' HitMask and MeMask fields in the base 
VSprite structure. If a set bit in the HitMask of one GEL 
matches a set bit in the MeMask of the other GEL, the colli- 
sion routine corresponding to that bit number is called. 

If you wish your VSprite or BOB to automatically perform 
collision-handling functions when it runs into something, ini- 
tialize it's base VSprite's collision handling fields: 

vsprite.HItMask 
vsprlte. MeMask 
vsprite.BorderLine 

vsprite.CollMask 



Note that these fields are all set to to completely disable 
collision handling for that GEL. Two areas of memory must 
be allocated for each GEL for proper collision detection. Coil- 
Mask points to a single plane of chip memory the size of the 
image. 

vsprite.CollMask = (DWORD *)AllocMem{(long)slzeof(UWORD) * 
vsprite.Wldth • vsprlte.Height, MEMF_CHIP); 

BorderLine points to a single line of chip memory as wide 
as the image. 

vsprite.BorderLine = (UWORD *)AllocMem((long)slzeof{UWORD) * 
vsprite.Wldth, MEMF_CHIP); 

These areas must reside in chip memory. CollMask will 
contain the shadow mask (a single plane with bits set where 
nonbackground pixels exist in the image), while BorderLine 
contains a "squashed-down" single-line version of the shad- 
ow mask for quick collision detection with boundaries. 

You set collision-handling functions with the SetCollision() 
function. 

ULONG num; 
void (*routine)(); 
struct Gelslnfo gelsin'o: 

SetCollislon(num, routine, &gelslnfo); 

Here, num is the collision-handler number to assign rou- 
tine to. This is the routine called when the respective bits are 
set in the HitMask and MeMask fields of the VSprite. gels- 
info is the pointer to the Gelslnfo structure used to manage 
your GEL list. 

A GEL-to-GEL collision-handler routine takes two point- 
ers to VSprite structures as its parameters. The first is the up- 
per-left GEL involved in the hit, and the second is the lower- 
right GEL. The upper-most GEL to the left is always the first 
GEL sent to the handler. 

There can only be one GEL-to-boundary function, and 
this is collision handler number zero. This routine takes a 
pointer to the VSprite that hit a boundary, and a flag WORD 
with bits set indicating which boundaries were hit or ex- 
ceeded. These bits are TOPHIT, LEFTHIT, RIGHTHIT, and 
BOTTOMHIT. 

The boundaries for GEL-to-boundary collision detection 
are set in the Gelslnfo structure. 

struct Gelslnfo gelslnfo; 

gelsinfo.topmost = 0; 
gelslnfo.bottommost = 200; 
gelsinfo. leftmost - 0; 
gels info, rightmost = 320; 

To actually test for GEL collisions, call DoCollision(). This 
is usually done immediately after the GELs are displayed, 
and will automatically call your collision handlers as need- 
ed (note that more than one may be called if more than one 
hit takes place, but only one handler will be called for any 
particular hit between two GELs). 

See the VSprite program on the disk for a complete exam- 
ple of the collision-handling system. 

GEL USER EXTENSIONS 

You can attach your own data to VSprites, BOBs, and Anim- i 
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Comps, allowing you to perform special processing as need- 
ed on your GELs. One common extension is acceleration and 
velocity support for VSprites and BOBs. 

To do this, you define a structure which will contain all the 
extra information you require. Here is an example: 

struct GELinfo { 
WORD x_vol; 
WORDy_vel; 
WORD x_acc; 
WORD y_acc; 

}; 

To extend the VSprite structure with this information, per- 
form the following define: 

#define VUserStuff struct GELinfo 

and to extend a BOB: 

#define BUserStutf struct GELinfo 
and to extend an AnimOb: 



-'(define AUserStuff struct GELinfo 

Note that you can not use the "C" 
typedef operator. You must use the de- 
fine construct. The structure and the 
above macro must be defined before 
the gels.h header is included. The pre- 
processor will now actually include 
your structure as part of the respective 
GEL structure. Access to this structure 
is available through the GEL's UserExt 
field. If you do not provide an exten- 
sion structure, UserExt is a WORD val- 
ue and can be used for user information 
of that size if desired. 

See the VSprite program on the disk 
for a complete example of user-exten- 
sion handling. 



not just right, the wheel will appear to slide across the sur- 
face upon which it is supposed to be only rolling. Ring mo- 
tion can be used to draw all of the frames for one revolution 
of the wheel in a fixed space. In each frame, the wheel will 
be drawn shifted a little as well, corresponding to how far it 
has turned. When being animated, the wheel "object" re- 
mains in place for a complete cycle of its frames, although be- 
cause of the way the frames are drawn, the it still appears to 
move. When the wheel has made one complete revolution, 
the wheel object's position is updated by a ring translation 
value, which corresponds to how far the wheel has actually 
travelled due to its turning. 

Hierarchical Motion is achieved by complex linkage of se- 
quenced and ring-motion frame sequences into one object. As 
the object moves, the individual animation sequences are also 
updated, and move with respect to the host object. For ex- 
ample, imagine animating a walking person. The head, arms, 
legs, and torso can each be sequenced motion frames, so as 
the person object is moved, the individual pieces move with 
the body and also swing back and forth and up and down as 
they normally would when a person walks. 

The primary component of an ani- 
mated object is the AnimComp: 



"The Amiga provides 

four levels 
of frame animation: 

simple, sequenced, ring, and 

hierarchical motion. " 



struct AnimComp { 
WORD Flags; 
WORD Timer; 
WORD TimeSet; 
struct AnimComp 'NextComp; 
struct AnimComp 'PrevComp; 
struct AnimComp 'NexISeq; 
struct AnimComp 'PrevSeq; 
WORD (*AnimCRoutine)(); 
WORD XTrans; 
WORD YTrans; 
struct AnimOb "HeadOb; 
struct Bob 'AnimBob: 



THE ANIMATION SYSTEM 

Finally, with the voluminous preliminaries out of the way, 
we will get into actual animation. As you are probably aware, 
animation is achieved by flipping through successive frames 
of images, each slightly different. If the frames are drawn 
properly, the result is fluid motion. 

The Amiga provides four levels of frame animation: sim- 
ple, sequenced, ring, and hierarchical motion. 

Simple Motion is achieved simply by moving an image 
across the screen a little at a time. Missiles and falling safes 
are examples of animation achieved with simple motion. 

Sequenced Motion is similar to simple motion, except as the 
object moves, its image changes as well. A rolling spoked 
wheel or a tumbling mahogany desk are examples of se- 
quenced motion. 

Ring Motion is similar to sequenced motion, except the ob- 
ject is usually anchored to something. Each image in a cycle 
of movement is drawn with respect to a common anchor 
point, and at the end of the cycle, the anchor point is updat- 
ed based on a certain value. Imagine using sequenced motion 
to move a spoked wheel What will happen if the velocity 
doesn't match the rate at which the frames are drawn? If the 
frames don't match up, and the object's translation value is 



Each AnimComp is linked toa BOB, 
which in turn provides the imagery for that component. For 
any animation object, at least one AnimComp is used. Ani- 
mComps also contain offsets, XTrans and YTrans, that are 
added to the host animation object's location to determine the 
component's location. These are deltas, and can he positive 
or negative (or zero, for that matter). AnimCRoutine can be 
a pointer to a user function that is called during the anima- 
tion stage. This function takes one parameter, a pointer to the 
AnimComp being handled. TimeSet is a counter indicating 
how many frames this component must be displayed before 
cycling to the next frame of the sequence. 
Each animation object is represented by an AnimOb: 

struct AnimOb { 

struct AnimOb *NextOb; 
struct AnimOb 'PrevOb; 
LONG Clock; 
WORD AnOldY; 
WORD AnOldX; 
WORD AnY; 
WORD AnX; 
WORD YVel; 
WORD XVel; 
WORD Y Accel; 
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WORD XAccel; 
WORD RingYTrans; 
WORD RingXTrans; 
WORD ('AnimORoLtineH); 
struct AnimComp "HeadComp; 
AUserStuff AUserExt; 



The AnimOb contains the location of the object and a point- 
er to the head animation component. It also contains linkages 
for the master object list, a pointer to a function that is called 
when the object is calculated (optionally provided by the pro- 
grammer, this routine takes a pointer to the AnimOb as its 
only parameter), ring translation values if the object uses 
ring-motion, and internal variables. Note also that AnimObs 
contain information for velocity and acceleration, but they 
still have user extension support. 

There's one difference between the coordinate system used 
for AnimObs and AnimComps. All coordinates are refer- 
enced as 16-bit, fixed-point binary fractions with the decimal 
at position six. This gives positional and incremental preci- 
sion down to 7m of a unit. A constant, ANFRACSIZE, is pro- 
vided for the proper shift value to get screen coordinates into 
this fraction format. Just shift all of your screen coordinate 
values to the left by ANFRACSIZE. If your AnimOb or Anim- 
Comp is being referenced from within a user function called 
by the AnimateQ function, don't forget to shift your object 
values back to the right by ANFRACSIZE to get the actual 
pixel location. 

Animation sequences and objects are set up in several 
different ways, depending on what type of animation you 
wish to perform. To set up a simple-motion animated ob- 
ject, all you need to do is initialize one AnimComp and 
point its AnimBob pointer to the BOB you wish to use for 
the imagery: 

struct Bob bob; 

struct AnimComp acomp = {0}; 

struct AnimOb animob = {0}; 

f initialize your BOB first 7 

bob.BobComp = &acomp; /* rink the BOB to its host 

AnimComp */ 

acomp. AnimBob = &bob; 

acomp. HeadOb = Sanimob; 

acomp.XTrans = 0; 

acomp. YTrans = 0; 

/• this component will be drawn wherever the AnimOb 

is drawn, since the offsets are zero 7 

animob.HeadComp = &aeomp; 

animob.AnX = 20 « ANFRACSIZE; /* don't forget! 7 

animob.AnY = 150 « ANFRACSIZE; 

/* the AnimOb is Initially drawn at 20, 150 7 

Now, when you move the AnimOb around, the specified 
BOB is drawn with it. This is essentially the same as handling 
the BOB yourself as a simple GEL, but the AnimOb handles 
things such as velocity and acceleration for you automatically. 

To accomplish sequenced and ring-motion animation, 
you'll need several BOBs and animation components, all 
linked together with the AnimComp PrevSeq and NextSeq 
fields. PrevSeq points to the previous AnimComp in the se- 



quence, and NextSeq points to the next one in the sequence. 
To loop the sequence, the last AnimComp's NextSeq points 
to the sequence's first AnimComp, and the first AnimComp's 
PrevSeq points to the last AnimComp in the sequence. Note 
that because there are multiple AnimComps, each can have 
different XTrans and YTrans values, and therefore different 
drawing positions relative to the host AnimOb. 

The only difference between the setup for sequenced and 
ring-motion animation is in how the frames are drawn, and 
specifying the RINGTRIGGER bit in the appropriate Anim- 
Comp Flags field. When that AnimComp is drawn, the Anim- 
Ob's RingXTrans and RingYTrans values are added to the 
AnimOb 's AnX and AnY location values. 

In both cases, the AnimOb HeadComp field points to the 
first AnimComp to be drawn in the sequence. 

struct Bob bob), bob2, bob3; 

struct AnimComp compl, comp2, comp3; 

struct AnimOb animob; 

f a three-frame sequenced ring-motion animation 7 

bobl.BobComp = &comp1 ; 

compl .AnimBob = &bob1 ; 

compl .PrevSeq = &comp3; f previous Is the last frame 7 

compl .NextSeq = &comp2; 

bob2.BobComp = Scomp2: 
comp2.AnimBob = &bob2; 
comp2.PrevSeq = &comp1; 
comp2. NextSeq = &comp3; 

bob3.BobComp = &comp3; 

comp3. AnimBob = &bob3; 

comp3. PrevSeq = &comp2; 

comp3.NextSeq = &comp1 ; /* loop back to frame 1 */ 

comp3.Fiags = RINGTRIGGER; f frame 3 moves the AnimOb 7 

animob.HeadComp = &comp1 ; 
animob.AnY = 150 « ANFRACSIZE; 
animob.AnX = 20 « ANFRACSIZE; 

animob. RingYTrans = 0; 
animob.RingXTrans = 20 « ANFRACSIZE; 

/' the AnimOb internal location Is moved 20 pixels to the 
right when frame 3 is drawn. The next time around, the 
object is drawn In the new location. 7 

Finally, for a complex hierarchical object, there can be more 
than one animation sequence in the object. In this case, mul- 
tiple sequences of AnimComps are linked together with the 
NextComp and I'revComp fields. The first AnimComp in a 
sequence is linked into the other sequences with these fields, 
just as sequence frames are. 

Another important consideration now is the drawing or- 
der of the respective BOBs that make up the frames. If not giv- 
en an explicit drawing order, the system will draw them in 
sorted order as it comes to them. You must use the BOB's Be- 
fore and After pointers to order your AnimComp drawing 
sequence. These pointers need only be assigned for the first 
AnimComp's BOB for each sequence, as are the NextComp 
and PrevComp fields. The first sequence's first AnimComp 
PrevComp field should be NULL, while the last sequence's 
first AnimComp NextComp field should also be set to NULL, 
indicating that there are no more sequences for this AnimOb. > 
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The code below describes an AnimOb with three parts. 
The first is just one image and doesn't change, while the sec- 
ond part has two frames and appears behind the first part. 
The third has three frames and appears in front of both of the 
other parts. 

struct Bob si bob; 

struct Bob s2bob1 , s2bob2; 

struct Bob s3bob1. s3bob2, s3bob3: 

struct AnimComp alcomp; 

struct AnimComp a2comp1, a2comp2; 

struct AnimComp a3comp1, a3comp2, a3comp3: 

struct AnimOb animob; 

f the Bob/AnimComp linkages are removed here lor brevity. 
Typically, these objects are allocated dynamically anyway */ 

alcomp.PrevComp = NULL; I' this is the first sequence V 

a1 comp.NextComp = &a2comp1 ; 

a2comp1.PrevComp = &a1comp; f second sequence 7 
a2comp1. NextComp = &a3comp; 

a2comp1.PrevSeq = &a2comp2; I' next frame is frame 2 'I 
a2comp1.Nex1Seq = &a2comp2; 

I* note that there is no PrevComp or NextComp linkage here. 
We only use the FIRST AnimComp in the sequence for linking 
multiple sequences 7 
a2comp2.PrevSeq = Sa2comp1 ; 
a2comp2.NextSeq = &a2compl; 

a3comp1 .PrevComp = &a2comp1; 

a3comp1 .NextComp = NULL; I' this is the last sequence */ 

a3comp1.PrevSeq = &a3comp3; 

a3comp1.NextSeq = &a3comp2; 

a3comp2.PrevSeq = &a3comp1; 
a3comp2.NextSeq = &a3comp3; 

a3comp3.PrevSeq = &a3comp2; 
a3comp3.NextSeq = &a3comp1 ; 

animob. HeadComp = &a1comp; 
/' now specify the sequence frame drawing order V 
r sequence 2 (two-frames) first '/ 
a2comp1.AnimBob—> After = NULL; 
a2comp1.AnimBob->Before = &a1comp.AnimBob; 

/' now draw sequence 1 (the single-frame part) 7 
alcomp. AnimBob— >After = &a2comp1.AnimBob; 
a1comp.AnimBob->Before = &a3comp1 .AnimBob; 

r and finally sequence 3 (three frames) */ 

a3comp1.AnimBob->After = Satcomp. AnimBob: 
a3comp1.AnimBob->Before = NULL; 

Note that it would be possible to have more than one com- 
ponent in more than one sequence of a ring-motion trigger 
frame. And be careful that you only specify one AnimComp 
as the ring trigger frame. 

The system keeps track of all of the animation objects in a 
list using an AnimKey pointer, which is simply a pointer to 
the most recently added AnimOb. You initialize this pointer 
as follows: 



struct AnimOb 'anlmkey; 

1nitAnimate(&animkey); 

Once your object has been set up properly, you can add it 
to the GEL system object list with AddAnimObQ. 

struct AnimOb animob; 
struct AnimOb 'animkey; 
struct RastPort rastport; 

AddAnimOb(&animob, fianimkey, Scrastport); 

You call the AnimateQ function to update all of the object 
positions and sequence frames before calling the other nor- 
mal GEL drawing routines. AnimateQ also calls any AnimOb 
or AnimComp user functions that may have been attached 
to the AnimCRoutine and AnimORoutine fields. 

Animate(anirnkey, &rastport); 

SortGList(&rastport); 

DoCo!lision(&rastport); I* if you deal with collisions V 

/* your collision handling functions may have reordered GEL 
priorities, so be sure to call SortGList() again so the 
system can put them in the right drawing order */ 

SortGList(Srastporl); 
DrawGList(&vlewport, &raslport);<f< 

VELOCITY AND ACCELERATION 

Velocity and acceleration are handled automatically for 
AnimObs by the system. The XVel, YVel, XAccel, and YAc- 
ce! fields are all referenced as fixed-point binary fractions, 

For each call to AnimateQ, XAccel is added to XVel and 
YAccel is added to YVel, then XVel is added to AnX and 
YVel is added to AnY, thus changing the AnimOb 's location. 
For example, to move an AnimOb right one pixel for each call 
to AriimateO, with acceleration of one pixel every 64 calls, you 
would set up the values as shown: 

animob.XVel = (1«ANFRACSIZE); f one */ 
animob.XAccel = 0x0001 ; /* 1/64th */ 

See the program Demo for a complete example of simple 
and hierarchical animation, double-buffering, and user Cop- 
per-list techniques. 

YOUR NEXT MOVES 

As you can see, a lot of effort was put into the Amiga's an- 
imation system. Although it is quite powerful, it's not really 
that hard to program when you look at it all from a com- 
pletely object-oriented point of view. The example programs 
should give you plenty of information about specific types of 
GELs and animation support, and if that isn't enough, the 
Amiga ROM Kcrnal Reference Manual Libraries (Addison-Wes- 
ley) and the Amiga includes and autodocs are invaluable ref- 
erence sources. ■ 

Paul Miller has been an Amiga developer since 1985. Recently 
he became involved in developing CDTV applications, as well. In 
his spare time, he uses his Amiga for graphic design and music com- 
position. Write to him c/o The AmigaWortd Tech journal, 80 
Elm St., Peterborough, NH 03458, or contact him via Internet 
(pmiller@csugrad.cs.vt.edu). 
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ARexx is for Writing 
Applications: Part II 

''Just a reminder" to finish the calendar utility 
you started programming in the last issue. 



By Marvin Weinstein 
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AREXX IS WELL SUITED to writing complicated applica- 
tions, or so I contended in part one of this article (p. 26, Jan- 
uary/February '92). As evidence of the fact, I offered a calen- 
dar/reminder utility written in ARexx, outlined the application, 
and detailed the calendar program. In this article, I provide fi- 
nal proof by describing the various programs, commands, and 
routines that comprise the reminder portion of the utility. 

In addition to calendar.rexx, covered in part one, the cal- 
endar/reminder utility consists of an interface program and 
a number of housekeeping programs. The longest and most 
complicated is setremind.rexx, which provides an Intuition 
interface for creating and saving reminders. The four re- 
maining programs handle housekeeping details, and should 
typically be included in the user's startup-sequence: Dore- 
minders.rexx launches current-day reminders; cleanre- 
minders.rexx erases expired reminders; for users who don't 
reboot their Amiga on a daily basis, reminddaemon.rexx runs 
the launch and clean programs once a day; and finally, re- 
mind. rexx posts the reminders at their scheduled times. 

INSTALLING AND RUNNING THE 
REMINDER UTILITY 

To install the reminder utility, decompress the file in the 
Weinstein drawer on the accompanying disk. Now, from the 
rexx directory copy the files setremind.rexx, remind. rexx, 
doreminders.rexx, cleanreminders.rexx and reminddae- 
mon.rexx to your rexx: directory. Finally, copy all of the files 
from the libs directory to your libs: directory. 

An environment variable, reminderdirectory, specifies 
where reminders are kept. Although you could set this vari- 
able by hand, setremind.rexx will handle this chore for you. 
(Please note that if you are not running AmigaDOS 2.0, 
you must assign the logical device env: to some directory. 
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If setremind.rexx fails to find an assignment for env:, it will 
not run.) 
To get started, go to a CLI and type: 

rx setremind 

The program first checks to see if reminderdirectory has al- 
ready been defined. If not, the program leads you through the 
process of defining the variable and creating a directory in 
which to store future reminders. Once the variable is defined, 
the custom requester will appear (see Figure 1). 

With the set-up complete, creating a reminder is simple. In 
addition to scheduling reminders for a specific day and time, 
you can have them recur at the same time every day or on a 
specific day each week. To schedule a daily reminder, type 
the word "everyday" in the string gadget that appears to the 
right of the Date: button. To schedule a reminder that recurs 
at a specified time on a given day each week, simply type the 
weekday you want: Monday, Tuesday, and so on. Only the 
first two letters of these words count and case is unimportant. 

To erase expired reminders go to a CLI and type: 

rx clean reminders 

To launch all reminders scheduled for the current day go 
to a CLI and type: 

rx doreminders 

You could add these commands to your startup-sequence 
to guarantee the operations occur each time you boot. If you 
don't boot your Amiga on daily, then instead add the line: 

run rx reminddaemon 

to your startup-sequence. This program runs cleanreminders 
and doreminders when the system clock strikes midnight. 

Once running, it is dif- 
ficult to kill reminddae- 
mon. To do so, go to a CLI 
and type: 

setenv remlndquit 1 

Now, use AmigaDOS' 
Status function to find the 
processes that are loaded 
as wait, and send each one 
a break. One will be the re- 
minddaemon. For exam- 
ple, if you type: 



.i.m.i: 



Add Reminder 



Figure 1: The reminder program'; cuslorr requester 
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and find a line that says something like: 

Process 6: Loaded as command: wait 

you should type: 

break 6 

Of course, the process number need not be 6. In the event 
that several reminders are scheduled, they will also be listed 
as command wait. Sending a break to a waiting reminder 
forces it to post its message immediately. If remindquit is set 
to 1, then sending a break to the reminddaernon will post a 
message saying that it is shutting down. 

SETREMIND'S MAIN PROGRAM 
This is a skeleton outline of the program setremind.rexx: 

/" rexxrsetremind.rexx 



calladdlibCrexxarplib.llbrary',0,-30,0) 

If showlist('p',REMINDERHOST) then exit 

FRESHSTART: 

reminderdirectory = CheckSetUpO 

call GetDateTimeO 

callMenuWIndowfREMINDERHOST.REMINDERPORT) 

RESTART: 



do forever 

if quftflag ■ 1 then leave 

t = waltpkt(REMINDERPORT) 

doff = 1 

p s gelpkt(REMINDERPORT) 

If c2d(p) = then leave ff 

command = getarg(p,0) 

parse var command command sc1 Sc2 sc3 . 

if command = "CLOSEWINDOW" ... then 

text = getarg(p,1) 
t = replyfp, 0) 
select 

when command = CLOSEWINDOW then do 



when command = "GADGETUP" 
& sd = "ADD" then do 



when command = "GADGETDOWN" , 
& sd = "SETHRS" then do 

end 

when sd = "DATE" then 

call ActivateGadget(REML. ,"MES1") 



when command = "GADGETUP" , 
& set = "CALENDAR" then 



address AREXX calendar REMINDERPORT 
when command = "DATEIS" then do 

end 

otherwise nop 
end 

end 
end 
exit 

The program begins with the obligatory comment and the, 
by now, familiar line that adds rexxarplib. library to ARexx's 
internal list. The next line of code uses ARexx's versatile 
showlistQ function to check for a RexxArpLib host called RE- 
MINDERHOST, because you don't want to open the re- 
minder-creation interface more than once. Because showlistQ 
is not properly documented in the ARexx manual or in the 
original 2.0 documentation, it is worth discussing here. 

AN ASIDE ON SHOWLIST0 

ShowlistQ returns information about shared system lists. 
The version provided with OS 2.0 (ARexx 1.15) has the 
syntax: 

Usage: showlist( option, [name], [separator]} 

where the options are A, D, H, I, L, M, P, R, S, T, V, W, which 
respectively stand for: Assigned directories, Devices, Han- 
dlers, Interrupts, Libraries, Memory-list items, Ports, Re- 
sources, Semaphores, ready Tasks, Volume names, and Wait- 
ing tasks. These options are useful when writing installation 
programs in ARexx. 

Separator, the third argument (optional), specifies a char- 
acter to place between the entries in the string showlistQ re- 
turns. For example, to produce a list of libraries wherein the 
names are separated by a % symbol, type: 

say showlist(T„'%') 

(Both commas separating the first and third arguments are 
required.) You can even use the hex character "0a"x as the 
separator, in which case a linefeed will be inserted between 
each entry on the list. Thus: 

say showlist("v"„"0a"x) 

produces a list of the form: 

RAM_0 
RAM DISK 
WORK 
AWTECH 

These options are particularly useful when one of the list- 
ed items contains a space, as in RAM DISK above. 

THE MAIN PROGRAM, CONTINUED 

Next, there are two label clauses, FRESHSTART: and 
RESTART:. These clauses define where ARexx will resume 
execution after encountering the instructions 

SIGNAL FRESHSTART 
SIGNAL RESTART 

found in the subroutines CheckSetupO and ProcessMessageQ. 
You will notice new material in these subroutines and in 
the subroutines GetDateTimeQ and MenuWindow(), I will 
discuss the new material later in the article. For now, you only 
need to know that when Menu Wind ow() returns successful- 
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ly, it will have created REMINDERHOST (a RexxArpLib 
host) and opened a message port named REMINDERPORT, 

The structure of the main loops is similar to that used in 
earlier examples, with some significant differences. There- 
fore, let's review the basic procedure for handling messages 
generated by an RexxArpLib host and compare it to the pro- 
cedure for handling messages generated by the Set Hours 
and Set Minutes gadgets. 

Message handling occurs within the main do forever loop. 
An if.. then statement at the top of this loop checks the vari- 
able quitflag. If quitflag = 1, the progTam leaves the loop, 
thereby ending the program. If quitflag at 1, the next state- 
ment executed is a call to ARexx's waitpkt() function. This 
causes the program to sleep until a message arrives at RE- 
MINDERPORT. When that happens, the program wakes up 
and executes the statements contained within the do ff = 1 
loop. Using a do name = 1 construction lets you refer to the 
loop by name in a leave name instruction. This helps avoid 
confusion, particularly because the leave instruction is used 
in more than one place. 

It is important to note that the inner loop, do ff = 1, keeps 
pulling messages from REMINDERPORT until no messages 
are left. Remember, after getpktQ is called, any messages 
queued at the message port will be ignored by subsequent 
calls to waitpkt(). In fact, calling waitpktQ before emptying 
the queue will seriously delay the handling of input events. 
(See"Custom Interfaces With ARexx," p. 28, November/ De- 
cember '91.) 

If a message is queued at the REMINDERPORT getpkt() re- 
turns a valid address. If no messages are queued, getpkt() re- 
turns the hex character "0000 0000"x. The statement: 

if c2d(p) a 

checks to see that getpktQ has found no waiting messages. 
The function c2d{) converts the hex string to a decimal num- 
ber. I use this construction because it works with all versions 
of ARexx. With newer versions of ARexx you can compare 
the value of p directly to the value returned by the ARexx 
function NULLQ. When a non-NULL address is returned by 
getpkt(p), the function getarg(p, number 0-15) extracts the in- 
formation stored in the waiting message. (Recall that a gen- 
eral ARexx message has 16 slots that can contain information 
and that getarg(p) is equivalent to getarg(p,0).) 

All of the button and string gadgets associated with the 
custom requester are created in the MenuWindowQ subrou- 
tine. If you examine this routine you will see that the button 
gadgets generate messages that contain information in only 
the slot, whereas string gadgets generate messages that 
contain information in both the and 1 slots. Don't forget that 
failing to reply to a message after extracting its contents is an 
invitation to disaster. 

In general, the slot of the ARexx message generated by 
clicking on a gadget contains a string consisting of up to four 
words. The first word will be either CLOSEWINDOW, the 
name assigned to the gadget when it was added to the re 
quester, GADGETUP, GADGETDOWN, or MOUSEBUT- 
TONS. After the first call to getarg(p) the variable command 
will contain this string. I use ARexx's parse var instruction: 

parse var command command sd sc2 sc3 . 

to separate this command into its component parts and at the 
same time assign the first word to command, the second to 
scl, the third to sc2, and so on. The dot that appears at the 



end of the line is a placeholder symbol indicating that any 
words that remain should be thrown away. It guarantees that 
sc3 will not contain a leading space. Placeholder symbols can 
also be used to discard words appearing at other places in the 
string to be parsed. Thus: 

parse var command . sd sc2 sc3 . 

would parse the string command and throw away the first 
word, assign the second to scl, assign the third to sc2, the 
fourth to sc3, and then throw away any material that follows. 

HANDLING NEW KINDS OF MESSAGES 

Once the variable command is parsed into its component 
parts, control passes to the select., when., otherwise section 
of the program. While the procedure used in this section is 
similar to that used in previous examples, significant differ- 
ences arise because our RexxArpLib host is now sending 
GADGETDOWN and MOUSEBUTTONS messages in addi- 
tion to GADGETUP messages. These messages are needed 
because the Set Hours and Set Minutes gadgets now work 
(for the user) like the buttons on a digital clock: Placing the 
mouse pointer over the Set Hours gadget and pressing the left 
mouse burton cycles the text through the numbers 1-12. 

Setting the GADGETDOWN flag in MenuWindow() tells 
the host to send a message whenever the user places the 
pointer over a button gadget and presses the left mouse but- 
ton. This is in addition to the GADGETUP message that is 
sent when the mouse button is released while the pointer is 
over the same gadget. But what if the user changes his mind 
and moves the pointer away from the gadget before releas- 
ing the mouse button? The MOUSEBUTTONS flag handles 
this event by indicating that a message should be generated 
whenever the user depresses or releases a mouse button 
when the pointer is not located over gadget. Because this is 
what the user normally does if he changes his mind, the pro- 
gram shouldn't respond to a message of this sort. Such a mes- 
sage is only necessary if the user starts the Set Hours (or Set 
Minutes) counter running and then moves the mouse point- 
er off the button before releasing it. In this case, if the program 
did not get a MOUSEBUTTONS message, the counter would 
keep running. The code that handles the other gadgets ig- 
nores MOUSEBUTTONS messages. 

HANDLING THE CLOCK GADGETS 

The following code shows how the Set Hours gadget is 
handled. It provides an example of using getpktQ to poll RE- 
MINDERPORT at high speed. Once the program enters the 
do icount = 1 loop, it simply pulls messages and ignores those 
that don't begin with GADGETUP or MOUSEBUTTONS. 
Once such a message is found, it immediately leaves the 
icount loop. It is safe to leave the loop without taking any fur- 
ther action, because control transfers back to the do ff = 1 
loop, which keeps polling REMINDERPORT until all wait- 
ing messages have been handled. 

when command = "GADGETDOWN" 4 sd = "SETHRS" 
then do 

do icount = 1 

lasthr = (!asthr+iy/12 

call Move(REMINDERHOST,180,42) 

call Text(REMINDERHOST,...) 

call Delay 5 

p = getpkt(REMINDERPORT) * 
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if c2d(p) - then do 

command = getarg(p.O) 

parse var command command rest 

t = repiy(p.O) 

if command = "GADGETUP" , 

I command = "MOUSEBUTTONS" ttiBn 
leave icount 
end 
end 
end 

THE AM/PM GADGET 

Another technique that appears in the main program relates 
to the AM/PM gadget. The label on this burton gadget is 
meant to cycle between AM and PM whenever it is clicked. 
Because RexxArpLib doesn't provide a mechanism for simply 
updating the text of a button gadget, the programmer has to 
remove the old version of the gadget and then restore it after 
modifying the text. I have discussed this technique in con- 
junction with updating the contents of a string gadget. In this 
case, however, it is also necessary to erase the old gadget im- 
agery before adding the new gadget. The sequence of steps in 
the following code shows how I accomplish this: 

when command = "GADGETUP" & set = "AMPM" 
then do 

ampmcount = (ampmcount+1 )II2 

if ampmcount = then ampmtext = "AM" 

else ampmtext = "PM" 

callRemoveGadget(REMINDERHOST,AMPM) 

call SetAPen(REMINDERHOST,3) 

cal!RectFIII(REMINDERHOST,460,35,476,44) 

call AddGadgetfREMINDERHOST > 

call SetAPen(REMINDERHOST,1) 
end 

Notice the use of the RexxArpLib function RectFillQ to 
erase the old gadget imagery. This is preceded by the call to 
SetAPen{), so the rectangle used to erase the imagery will be 
filled with the background color. Once the old gadget is 
erased, the RexxArpLib host is instructed to add back new 
gadget, and then to set the APen back to its original value. 

CYCLING THROUGH THE STRING GADGETS 

The final new technique used in the main program in- 
volves cycling through the string gadgets when the user hits 
a carriage return. Implementing this feature is simple, if you 
remember that hitting a carriage return while in an active 
string gadget results in a GADGETUP message. Because 
MenuWindowQ defines string gadgets to return their name 
in the slot, all you have to do is add such a line as: 

when DATE then 

call ActivateGadget(R EMINDER H OST.MES1 ) 

This activates the gadget named MES1 whenever the user 
presses Return while the gadget named DATE is active. See 
the listing on disk for additional comments and refer to 
RexxArpLib.doc for the syntax of all RexxArpLib commands. 

THE SUBROUTINES 

The subroutines found after the main section of setre- 
mind.rexx introduce some new material, as well. 

The subroutines used in previous articles were fairly sim- 
ple, so I did not worry about subroutine variables having the 



same name as variables used in the main program. Once an 
ARexx program begins to get complicated, it is important to 
be able to limit the scope of a variable to a specific subrou- 
tine. This can be done by defining the subroutine as a PRO- 
CEDURE, which is accomplished by inserting REXX's PRO- 
CEDURE instruction after the label that indicates the 
beginning of the subroutine. For example: 

WriteFile: PROCEDURE 



return 

The word PROCEDURE can appear anywhere within the 
body of the function, but you should put it on the same line as 
the label or on the next line. Declaring a subroutine as a pro- 
cedure means that variables in the main program are protect- 
ed from alteration by a call to the subroutine. Although keep- 
ing variables local to a subroutine makes for safer programs, 
programmers often wish to give the subroutine selective access 
to specific variables. The EXPOSE subkeyword provides REXX 
with a mechanism for doing this. For example: 

WriteFile: PROCEDURE EXPOSE Isayit ... nag ... 

says that the variables contained in the list following the word 
EXPOSE will be available to WriteFile() for use and modifi- 
cation. The listing provides examples of the use of the PRO- 
CEDURE instruction with and without the EXPOSE keyword. 

A USEFUL TRICK 

In complicated programs, defining a list of global variables 
at the beginning of a program, then having subroutines use the 
same list makes it easier to organize. A sneaky use of REXX's 
INTERPRET instruction makes this possible. For example: 



globalsl = "varl var2 var3 var4" 



WriteFile: interpret expose globalsl 

makes varl, var2 and var3 available for use in WriteFileQ. 

CHECKING THE USER'S SETUP 

The subroutine CheckSetUpO looks to see if the environ- 
ment variable reminderdirectory is defined. If the variable is 
not, CheckSetUpO leads the user through the process of 
defining this variable and creating a directory in which to 
store future reminders. Determining whether a file, directo- 
ry, or logical device exists is easily done with the ARexx func- 
tion exists( filename), as in: 

say exists('env:reminderdirectory") 

However, if the device referred to does not exist, or has not 
been assigned, a call to this function causes an automatic re- 
quester to appear. This is annoying if you want to check for 
a file without letting the user know. Fortunately, the latest 
version of the infamous PragmaQ function provided with 
ARexx 1.15 lets you shut off the automatic requester. 

Pragma() is a kind of grab bag function that handles an as- 
sortment of jobs related to extracting and changing the attributes 
of the system environment. I used this function in the first in- 
stallment of this article to generate a unique Id for each invoca- 
tion of calendar.rexx. In CheckSetUpO I use PRAGMAQ to shut 
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off automatic requesters by calling it with the arguments: 
call Pragma('W','Null') 
To turn automatic requesters back on, I issue the call: 

call Pragma('W','WorkBench') 

The remainder of CheckSetUpO uses techniques familiar 
from previous articles. Refer to the comments contained in 
the listing for details. Note in particular the use of Rexx- 
Arp Lib's getenv() and setenv() functions to check for and 
write environment variables. 

THE SIGNAL INSTRUCTION 

REXX's SIGNAL instruction can be used in two ways. First, 
it can control the state of the program's internal interrupt 
flags. In this case the SIGNAL instruction must be followed 
by the keyword ON or OFF, and a one of the condition key- 
words, such as BREAK_C, SYNTAX, ERROR, NOVALUE, 
and so on. This mode of operation allows you to take full con- 
trol of what happens after the ARexx interpreter encounters 
an error, finds an undefined variable or one of the other spec- 
ified conditions. Although this can be extremely useful, I 
have not employed it in the calendar/reminder facility. 

In its second use, the SIGNAL instruction can be a kind of 
goto statement; it is used to transfer control to a label state 
ment located elsewhere the same subroutine, or in the call- 
ing program. Thus, if there is a label clause: 

FOOBAR: 

located somewhere in an ARexx program, the instruction: 

SIGNAL FOOBAR 

causes execution to transfer to the label clause. 

Be careful: The SIGNAL instruction is only somewhat like a 
goto statement. The actual purpose of SIGNAL is to permit 
flexible handling of error conditions; it is not meant to be a 
general-purpose programming tool. When ARexx encoun- 
ters a SIGNAL instruction, it completely dismantles all active 
control statements, including IF, DO, SELECT, INTERPRET, 
and interactive TRACE, before transferring control to the la- 
bel clause. Attempting to use SIGNAL FOOBAR to transfer 
control to another point within a do loop or select.when.. 
structure is doomed to failure. 

Only the control structures belonging to an executing sub- 
routine are dismantled when a SIGNAL instruction is en- 
countered. This means that using SIGNAL to transfer control 
from a subroutine to a label found in a calling program is safe 
and that is why 1 can use SIGNAL as I do in the subroutines 
CheckSetUpO, ProcessMessage(), and BadDate(). (See the list- 
ing for additional comments.) 

MAKEMENU 

The MakeMenu{) subroutine is much like its counterpart 
in calendar.rexx, with a few significant differences. One is that 
I ask for GADGETUP and MOUSEBUTTON events by adding 
these options to the line defining the variable idcmp that is 
passed to RexxArp Lib's OpenWindow() function. For example: 

idcmp = "CLOSEWINDOW+GADGETDOWN" 
Idcmp = idcmpll'+GADGETUP+MOUSEBUTTONS" 

Another difference is that the calls to AddGadget() create 
message strings that are more complicated than in previous 
examples, such as: 



AddGadgetL. ."CALENDAR", "Date:","%l %d") 
AddGadget( .. ."DATE", .. ,"%l %d%1%g",500) 
AddGadget( .. ,"%d%1%g'\500) 
AddGadget( .. ,"%l %d%1%d") 

In each of these cases I use the % mechanism provided by 
RexxArpLib to specify the structure of the message to be re- 
turned, see rexxarplib.doc for details. Briefly, %1 translates to 
the GADGETUP, GADGETDOWN, or MOUSEBUTTONS 
depending upon the IDCMP class of the event; %d translates 
to the name of the gadget that caused the event; %1 says put 
the material to follow in the first slot of the message; %g, 
used only for string gadgets, says "put the contents of the 
gadget in this place. " Thus, clicking on the Date: gadget pro- 
duces the message: 

GADGETDOWN CALENDAR 

and releasing the mouse button while the mouse pointer is 
over the same gadget produces: 

GADGETUP CALENDAR 

It is worth examining the use of ARexx's right() function to 
format the text that is written next to the Set Hours and Set Min- 
utes gadgets. This function, as well as left{), centerQ, copies(), 
overlay(), insert(), substr(), and subwordQ; are extremely use- 
ful when the program has to produce formatted text. 

GETVAR AND WRITEFILE 

The GetVar() subroutine, familiar from previous articles, is 
called in WriteFilef) to read all string gadgets before writing 
the reminder. This procedure enables the program to pick up 
any changes the user might have made in a string gadget 
without hitting a carriage return. 

When you look at the listing, note the use of ARexx's open(), 
close(), and writeln() functions to create the permanent copy 
of the new reminder. When using ARexx's openQ function, 
programmers often fail to specify its third argument, either R 
or W, to indicate whether the file is to be opened in Read or 
Write mode. If this argument is not specified ARexx will, by 
default, open the file in Read mode and subsequent calls to 
writeln() will fail. 

HOUSEKEEPING PROGRAMS 

The programs doreminders.rexx, remind. rexx, cleanre- 
minders.rexx, and remind daemon, rexx are short ARexx pro- 
grams designed to handle specific chores. The only two func- 
tions used in these programs that have not been discussed are 
explained in the ARexx manual, in the OS 2.0 documentation, 
and in the comments included in the listings. The most in- 
teresting aspect of these programs is the way they use 
ARexx's ability to launch Amiga DOS commands to achieve 
their ends. For example, remind.rexx speaks the reminder 
message by writing it to an external file and then sending it 
to SPEAK:. 

Whether or not it helps you remember your mother's birth- 
day or be on time for staff meetings, this calendar/ reminder 
program is convincing proof that ARexx can be used for cre- 
ating serious applications. ■ 

Marvin Weinstcin uses ARexx and REXX extensively in his 
xoork at the Stanford Linear Accelerator. Contact him c/o The 
AmigaWorld Tech Journal, 80 Elm St., Peterborough, NH 
03458, or on BIX (mweinstein). 
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Designing the User Interface: 

Text Fonts 



By David "Talin" Joiner 



ONE THING THAT always impresses me is an applica- 
tion's font awareness (or lack thereof). A number of programs 
look terrible on my system, simply because the programmer 
didn't consider that the application might be run on a system 
with a default font other than topaz-8. 

The simplest way to avoid this problem is to hardcode a 
font into your application. With this method, however, the 
window's title-bar font is taken directly from its screen font, 
and you can't change the font for the Workbench screen. (Not 
on my Workbench you don't!) Therefore, you have to open 
a custom screen, which isolates your program from the oth- 
er Workbench windows. I call it "The Custom Screen Leper 
Colony." 

A more advanced method entails repositioning your on- 
screen elements (buttons, gadgets, and so on) based on the 
font size. It sounds like a lot of work, but is actually easier 
than the methods many of us are accustomed to. 

For example, I used to design my windows and screens in 
DeluxePaint. Once the screen was finished, 1 would painstak- 
ingly write down the coordinates of every gadget, outline 
box, or static text, and then write the corresponding code into 
my program — a tedious task. 

With the new method, when I want a vertical column of 
gadgets, I write a function that iterates through the gadget 
list, placing each gadget just below the last. Modifying the 
function to adjust for the font size is easy. The result: I never 
have to write down the coordinates — the program figures 
them out for me at runtime. 

For more complex layouts you need to define a relationship 
between the various parts. For example, if I have a scrolling 
list next to a vertical column of buttons, my program loops 
through all of the buttons' text labels to see which is the 
largest, in pixels. After adding a reasonable amount of space 
to that for borders and inter-gadget spacing, it lays out the 
column of gadgets. This gives me the column height. Because 
the scrolling list is to the right of the column, I already know 
the left edge, top edge, and height of the scrolling list. All that 
remains to determine is its width, which can be either fixed 
or based on the width of the window (if that is known). 

Sometimes I work from a fixed window size (as when I 
clone the Workbench screen size), and other times I use a 
variable window size, making it just big enough to hold all 
the gadgets. Note that under OS 2.0, screens can actually be 
larger than the video display. Because you probably don't 
want to open your window larger than the actual video dis- 
play, you'll need to look at the DisplayClip variables that are 
accessed through the new ViewPortExtra functions in the 
graphics library. 
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Next, consider the window's title bar, which will change 
size based on the screen font. If the window is already open, 
determining the title bar size is easy: Just look at the size of 
the top border. Otherwise, you can use the screen's BarLay- 
er size or add three to the screen's font size. I've been told that 
the constant 3 is not likely to change in the future. 

You'll need to adjust your menus to the font as well. See 
"Menus for a New Generation" (p. 4, April/May '91) for 
ideas about accomplishing this. 

TEXT SUPPORT 

Fonts also affect the display of documents. In general, there 
are four possible levels of font support within a document: 

1. No font support: Document font is a hard coded, mono- 
spaced font, (old programs) 

2. Monospace font support: The document font can be any 
one, monospaced font, (text editors) 

3. Proportional font support: The document font can be any 
one font, (outline processor or low-end word processor) 

4. Multifont support: The document may contain more than 
one font, (full-featured word processor or desktop pub- 
lisher) 

At levels 3 and 4, rendering speed becomes a problem. As 
we all know, when rendering, calculating word wrap, and 
clipping to document borders, proportional fonts are slow- 
er than monospaced fonts. Fortunately, there is a handy 
way to speed up rendering and simplify clipping. This tech- 
nique works in any application that doesn't support multi- 
colored fonts (it can work for multicolored rendering, but 
it's trickier). 

Basically, you create an off-screen bitplane that is as tall as 
the largest font used in the program, and as wide as the line 
to be rendered (which can be wider than the window's draw- 
ing area). If you don't know what these dimensions will be, 
estimate the size and reallocate the bitplane later if needed, 
for a slight speed penalty. 

Each time you render a line of text, use the normal TextQ 
call into the off-screen bitplane. If your application supports 
more than one font size, you'll probably first want to clear the 
bitplane using the Blitter. For even greater speed, create your 
own text-rendering routines that write directly to the off- 
screen bitmap. (If your characters are small, it's faster to use 
the CPU than the Blitter to draw them). 

Once the characters are rendered, you need to clear the buf- 
fer from the end of the last character to the end of the buffer. 
The call ClearEOLQ in the graphics library will do it for you. 
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Finally, useBltTemplateQ to 
blast the bits from your off- 
screen buffer to your win- 
dow's drawing area. You don't 
need to create a clip region for 
this, simply adjust the coordi- 
nates of the source and desti- 
nation bitmaps/ rastports. 

If your text is always drawn 
in color 1, you can optimize 

even further by rendering only into the lowest bitplane of 
your window. (You'll need to insure that the other bitplanes 
are kept cleared, although you can use them to highlight 
text.) To do this, make a copy of the window's rastport and 
set that copy's rp_Mask to 1. Then use the copied rastport to 
do the BttTemplateQ. The other bitplanes are never touched. 
(Another trick: If you change pens or other rastport fields a 
lot, you can save time by keeping several copies of the rast- 
port around, each with its own settings.) 

FONT MENU VS. FONT REQUESTER 

Originally, most Amiga programs let the user select fonts 
from a menu. As users accumulated more fonts, however, the 
menus became so large that they ran off the bottom of the 
screen. Even worse, because menus are not clipped to the 
window boundaries for speed reasons, this sometimes caused 
system crashes and blanking displays. 

Scrolling menus like those on other graphical user inter- 
faces seem like a possible solution. The Amiga currently 
doesn't support scrolling menus, though, and there are a 
number of user interface experts that think scrolling menus 
are a bad idea. 

The officially adopted solution is to have a font requester 
that allows the user to browse though the fonts using a 
scrolling list, much like a file requester. In fact, the new op- 
erating system provides a font requester as part of the ASL 
library. (For details on asl.library, see "Easy File and Font 
Requesters," p. 7.) 

EMBEDDED FONTS 

Sometimes you'll want a unique font for your application 
(for example, a font of musical symbols for a music program). 
You can avoid the clumsy step of copying the font to the 
user's font drawer by embedding it within your application. 
There are a number of freeware utilities that convert fonts to 
C source code or assembly language. You can then use the 
font directly in your application without opening it. You'll 
probably need to make sure, however, that the actual font 
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data is in chip RAM. From 
what I've determined, some 
versions of the OS require the 
font data to be in chip RAM, 
while others don't. 

One caveat: Under 2.0, 
when you SetFontQ a font to a 
rastport, extra information for 
that font is allocated. Normal- 
ly, this information is deallo- 
cated when you close a font, but because embedded fonts are 
never closed, you will lose about 20 bytes of memory. You 
can forcibly deallocate the extra information using the new 
2.0 routine StripFontQ. 

FONT FUTURE 

There are a couple of advanced font features that may ap- 
ply to your application. The first is ColorFonts, a standard for 
those fonts containing more than one color. The ColorFont 
standard is part of the OS 2,0 (1.3 had a ColorFont utility to 
take care of it). The standard graphics library routine TextQ 
will automatically handle the details of rendering a color 
font, but there are some details, such as color remappings and 
palette selections, that your application might want to deal 
with in the context of a ColorFont. 

Outline fonts, the second new feature, are fonts that are 
stored as polygons rather than as bitmaps. Commodore has 
been working on the technology to bring outline fonts to the 
Amiga, and direct support for them is available in OS 2.0. 
Outline fonts are accessed like normal fonts. (When you open 
an outline font, it creates a normal bitmap font in that point 
size. When you close it, the bitmap representation is deallo- 
cated,) However, outline fonts can be opened in any point 
size. Your font requester should be able to detect an outline 
font and allow the user to enter any size, rather than just the 
standard sizes listed. 

WRAPPING UP 

As with many aspects of 2.0, with fonts you can no longer 
count on constant defaults. Build flexibility into your pro- 
grams and you never need visit the Custom Screen Leper 
Colony. ■ 

David "Talin" joiner is the author ofMusk-X and Faery Tale 
Adventure, plus an artist, aivard-ivinning costume designer, and 
moderator of the user. interface topic of the Amiga.sw BIX confer- 
ence. Contact them c/o The AmigaWorld Tech Journal, 80 Elm 
Si. Peterborough, NH 03458, or on BIX (talin). 
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Utilizing the 
Revision Control System 

RCS can help save time, hassles, and money 
during program development. 

By Bryce Nesbitt 



MANY TOOLS CLAIM to increase productivity, but not all 
live up to their promise. In almost ten years of continuous use 
in large UNIX-based environments, the Revision Control Sys- 
tem (RCS) has proven its value. Written by Walter F. Tichy 
and made available free of charge through his and Purdue 
University's kindness, RCS has been entrusted with the 
crown jewels of hundreds of major projects, including the 
source code for all versions of the Amiga operating system. 
Now the advantages of a large-systems development tool are 
available to Amiga programmers, thanks to Rick Schaeffer 
and Raymond S. Brand, who ported it over. 

Don't be scared by the word "control." RCS is unlike some 
so-called CASE (Computer-Aided Software Engineering) 
tools that are merely thinly veiled attempts at Orwellian con- 
trol. Unlike those tools, RCS does not force you to think, act, 
program, and operate in a certain manner. Designed for pro- 
grammers by programmers, the defaults of RCS perform rea- 
sonable actions. If the defaults are inappropriate, you can 
override or subvert RCS operations. RCS won't get in your 
way, at least not for long. 

WHAT'S IN IT FOR ME? 

RCS acts as librarian for your source code, offering com- 
mands for check in, check out, and housekeeping activities. 
In addition, RCS handles all file management and tracking. 
Previous versions of source code are stored as "reverse 
deltas." This compact format keeps many past revisions of the 
source within convenient reach. The benefits may seem sub- 
tle at first, and it all may sound complex, but experience will 
quickly show the ease and advantages: 

• RCS saves multiple revisions of your code seamlessly. Mod- 
ifying a source file does not destroy the older revision. You 
can quickly recall or compare any arbitrary revision. 

• RCS can mark an entire set of files as a "release." You can 
quickly revert to a release for comparison, regeneration, bug 
tracking, or any other purpose. 

• RCS offers powerful branch and merge facilities (more on 
this later). Two parallel versions of your product can be un- 
der development simultaneously without the usual hassle or 
wasted work. 

• RCS minimizes storage space. Rather than keeping sever- 
al copies of your source code, RCS stores only deltas or dif- 
ferences. Unless you change every line of every file with each 
revision, the delta format is likely to be smaller. 

• RCS provides access control for multiple programmers 
working on the same project, preventing two programmers 
from simultaneously overwriting each other's work. Mem- 
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bers of a team can keep track of a project's progress by view- 
ing RCS logs. With RCS, changes made by one programmer 
are instantly obvious to all others. 

• RCS allows mistakes to be easily reversed. If a change turns 
out to be a disaster, simply ask RCS for the old version back. 
Even if you accidentally deleted a section, RCS can quickly 
recover the missing lines. 

• RCS tracks the when and where of changes. Changes are 
logged into RCS with the time, date, and a short description. 
During development these log messages provide convenient 
reminders. Even years later these logs can be valuable to the 
people maintaining the original code. 

• RCS allows you to create test or experimental versions with- 
out risk to the main-line development. For example, you 
might try a new approach, search for an empirical solution 
to a problem, or test out a new idea. Without RCS you could 
easily forget debugging information or "temporary" changes. 
Some compatibility problems with 2.04 Kickstart were caused 
by old code that nobody intended to leave in the product. 
RCS lets you check in intermediate versions, thereby pro- 
tecting them from harm. When the test or experiment is com- 
plete the new source can be compared against the stable ver- 
sion, and desired changes automatically merged. 

• RCS is a fantastic aid in debugging; you can test solutions 
to a problem without risk to the main source code. If a new 
problem has been introduced into a previously working proj- 
ect, revisions can be peeled away until the bug is located. Re- 
viewing the source of problems can be instructive; was it late 
at night? Were there many distractions or phone calls? 

• RCS for the Amiga is fully interoperable with RCS for oth- 
er systems. RCS has a wide enough installed base to be a 
good system for distributing source code. 

• RCS is a perfect companion to networks. The RCS files can 
be stored on a central server (available to all programmers), 
while each programmer maintains a local working area. RCS 
was, of course, designed horn the start for multitasking multi- 
user computers. 

INSTALLING RCS 

At this point you should install RCS, which (along with 
code from Richard Stallman's Free Software Foundation) is 
found in the accompanying disk's Nesbitt drawer. Now, fol- 
low along with the example. Installing RCS is a snap. You'll 
need about 400K of hard-disk space and a few minor addi- 
tions to your s:User-Startup file: 

setenv USER NAME bryce 
assign RCS: work: bin 



- 



RCS/hella.c,v; Working file: hello.c 
1.3 



^ 



^ 



RCS file: 

head: 

branch: 

locks: : strict 

access list: 

symbolic names: 

comment leader: " * " 

total revisions: 3; selected revisions: 3 

description: 

My first C program. 



USERNAME is a Shell environment vari- 
able. RCS will tag all operations with this 
name. If multiple people will be accessing 
files, be sure that all names are unique. RCS 
prevents differing user names from modify- 
ing files in an inconsistent manner. 

The "assign RCS:" command must point to 
the storage location for the RCS executables. 
If you are short of hard-disk space and don't 
need merging capabilities, you may delete the 
files diff3, merge, rcsmerge, and ident. Be 
warned, however, that RCS is not recom- 
mended for floppy-based systems. 

Most UNIX programs, RCS included, depend on the avail- 
ability of large or infinite stack space. You'll need a stack of 
20K or greater to stay out of trouble. Add the following to 
your s:shell-startup: 

stack 20000 

IS IT REALLY THIS EASY? 

The three most used RCS commands are ci (Check In), co 
(Check out), and RCSDiff (show differences). An example 
should make things clear. Assume you just created a file 
called hello.c: 

cd RAM: 

makedir RCS ; storage for RCS files 

ci hello.c 

RCS prompts you for a short description of the file. In this 
case the description might be "My first C program." The 
working file hello.c will be deleted; don't panic! The file is 
safe in the RCS library. Before viewing or modifying a file, 
you must first check out a copy. Check out may either be un- 
locked, -u, or locked, -I. You can modify only locked files: 

co -I hello.c 

After your edits and testing are done, you would typical- 
ly compare the current version with the last check in. This 
step provides verification that you made only intentional 
changes and a mental jog for describing your changes: 

rcsdiff hello.c 

All differences are shown on the screen. If you are satisfied 
with your work, complete the loop by checking in the new 
revision: 

ci hello.c 



revision 1.3 

date: 91/11/10 15:01:23; author: bryce; state: Exp; lines added/del: 2/2 

Added loop counter printout. 



revision 1.2 

date: 91/11/10 14:59:54; author: John; state: Exp; lines added/del: 4/1 
Added loop to print string ten times- 
revision 1.1 

date: 91/11/1014:58:36; author: bryce; state: Exp; 
Initial revision 



Figure I. Sample outpjl Irom Rlog. 



RCS prompts you for a brief description of the changes. Try 
this yourself; the Nesbitt drawer on disk contains a sample 
hello.c file you can play with. 

WHERE IS IT HIDING MY CODE? 

RCS processes RCS delta (or ,v) files. To save clutter, it is 
best to create a directory called RCS in each location you use 
RCS. By default, RCS appends ,v to your filename and stores 
the result in the RCS/ directory. The RCS delta file is the cen- 
tral repository for all information about a file. If you wish to 
view a file, you must request a "working file." Working files 
may be checked out unlocked or, for modification, locked. 
You perform all normal edit and view actions on the work- 
ing file using standard text tools. 

Upon completion of a release or major feature, you should 
check in the code. RCS compares the working copy with the 
previously stored version, and stores the differences. RCS 
can recreate any old version on demand. 

The RCS delta file is stored in plain text. This can be com- 
forting; even if some bug or problem were to arise with 
RCS, your code could easily be recovered by editing the 
delta file. The grammar of the delta file is fully described in 
the documentation in the Nesbitt drawer of the accompa- 
nying disk. 

WHAT CAN I DO? 

Ten binary commands and one script are provided with the 
RCS distribution. I'll describe each only briefly; for detailed 
documentation, consult the .doc files in the Nesbitt drawer. 
As you read about each command, give it a try on your Ami- 
ga. I included several sample RCS files on the disk. 

rlog (RCS Log): Displays status, current revisions, lockers, 
brandies, and so on. See Figure 1 for an example. The scope of 
the information printed by rlog can be filtered by date, revi- 
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sion numbers, user name, outstanding locks, or other criteria. 

RCSDiff (RCS differences): Compares versions of a file. By 
default RCSDiff compares the current working file with the 
most recently checked-in version, RCSDiff can also compare 
against an older revision or compare two older revisions. 

res: The master control program. Res has command line op- 
tions for forcing locks, setting symbolic revisions, changing 
access lists, appending text, and so on. Unless your needs are 
obscure, you will use the res command infrequently. 

ci (Check In): Deposits new revisions into the RCS ,v file. 
Ci automatically compares the files and complains if no 
changes have been made, if the file is locked by someone 
else, or if the file was never locked at all. By default the revi- 
sion number is bumped; if the previous revision was 1.0, the 
next will be 1.1. You can force a new revision number with 
the -r option. By default, ci deletes the working file. The -1 
or -u options cause ci to preser\ e a locked or unlocked copy. 
For convenience, I alias ci to ci -u. 

co (Check out): Pulls information from the RCS ,v file. Files 
can be checked out unlocked, -u, or locked, -1. The -r option 
allows any older version to be selected. You can also select 
revisions by date or user name. In addition, 00 performs key- 
word text substitution. If the string $Id: S is found, it will be 
replaced with the file's name, revision number, date, author, 
and locker. It is a good practice to place $M: S at the top of 
each file checked in with RCS. Other keywords are listed in 
the disk-based documentation. 

diff: An excellent implementation of a popular difference 
generator is included with RCS. The command RCSDiff calls 
diff for the dirty work. Diff compares two files, showing any 
differences with > and <. Lines unique to the first file are 
prefixed with <. Lines unique to the second are prefixed w r ith 
>. It's easy to keep the arrows straight if you remember "the 
arrow points at the name on the command line." 

ident: Searches a file for keywords of the form SKeyword: 
$. Ident is sometimes used to extract embedded revision 
numbers from binaries. All of the RCS binaries contain in- 
formation in ident format. The AmigaDOS version command 
performs the same type of function for 2.04 Workbench. 

merge, RCSMerge, diff3: Show or process the relation- 
ship of two different modifications to the same base file. 
(More on these commands later.) 

RevLabel: This script attaches a symbolic revision to a set 
of files. Later, you can extract files using this symbol, even if 
the individual file version numbers vary wildly. It is a good 
idea to RevLabel each major or customer release. 

IT BRANCHES, SINGS, AND DANCES 

Imagine you've released versions 1 .0 and 1 .1 of your prod- 
uct. You are happily working on version 2.0 when an im- 
portant customer finds a major bug in 1.1. With RCS the sit- 
uation, while not pleasant, is at least manageable. 

RCS can keep track of multiple development threads (see 
Figure 2). With it, you can make revisions to version 1.1, with- 
out duplicating the source code or interfering with develop- 
ment of version 2.0. When the time comes to apply the same 
fixes to version 2.0, the RCSMerge command automates the 
work. RCSMerge performs a three-way diff, resolving con- 
flicts between two modifications of the original 1.1 code. Any 
overlap (lines modified by both the bug fix effort and the 2.0 
development) are highlighted for special attention. The ac- 
companying disk contains a sample of such branching. 

RCS is not limited to source code. Any sort of text may be 
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Figure 2. RCS branching helps manage multiple development threads . 

enshrined in RCS. Commodore uses RCS for keeping track 
of books in the library, compact discs available for listening, 
standards documents that may evolve over time, and public 
"idea" files to which everyone is encouraged to contribute. 
Creative uses for RCS abound. 

On the light side, RCS helped establish the Commodore- 
Amiga World Record for the longest undetected serious bug. 
Early in 1991 a ten-instruction timing hole was discovered in 
Exec PutMsg(). Searching the RCS logs revealed the source 
of the problem. A certain programmer had optimized the 
code for space years before. RCS had faithfully recorded the 
time, date, and changed lines. The date of change? Mid-1985. 

RCS has a few more handy tricks for you. For example, to 
check-out all RCS files for viewing type: 

spat "co" RCS/#? 

You can show all files with existing locks via: 
spat "rlog -L -R" RCS/#? 

If you happen to forget to lock a file before making 
changes, don't worry. Simply type: 

res -I filename.c 

To compare the current working file with the last checked- 
in version, issue the command: 

resdtff filename 

Comparing two revisions, on the other hand, requires: 

rcsdlff-r1.1 -rl.O filename 

Go ahead, give RCS a try on the sample files. You'll soon 
be ready, and eager, to let it help you with your own code. ■ 

Bryce Nesbitt, formerly a Commodore-Amiga employee, worked on 
many technical aspects of the Amiga, authored Enforcer, and head- 
ed the Operating Systems Development Group for the final phases 
of the Release 2 project. Contact him c/o The AmigaWorld Tech 
Journal, 80 Elm St., Peterborough, NH 02458, or on BIX (bnesbitt). 
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END IF 

LIBRARY CLOSE 
END 

THE C PROGRAM 

This program needs to know no Amiga structures, and 
uses no "standard" C library commands. So, amazingly, it 
needs no include files at all! We might still choose to include 
proto/dos.h or libraries/dos.h — these would help with def- 
initions such as that of MODEJDLDFILE. 

Our program does not need to open any system libraries. 
We use functions from dos.library only; and that has been au- 
tomatically opened by the C system. 

To keep the program short, I have not included extra cod- 
ing to read the contents of the temp file. 

I* This demo program shows how to 7 

f invoke Amiga's DOS library */ 

f EXECUTE routine from C coding 7 

/• We must use Open/Close to allow */ 
f operation from Workbench start! 7 

main() 

{ 

long handle; 
/■ Open NIL: as a file to allow output path 7 

handle = Open("NIL:",1005); /* MODE_OLDFILE 7 



If (handle != 0) 
/* Invoke the dos.library Execute function 7 
f success = ExecutejcommandString, input, output handle) 7 

{ 

Executef'list >RAM:temp lformat=%s", 0, handle); 
I' the file handle to NIL: has done its job; close it 7 
Close(handle); 
} 
/" This example won't show the code to list file RAMrtemp 7 
} 

EXTRA WORDS 

Some varieties of BASIC for the Amiga have keywords 
that allow commands to be sent directly to the CLI/Shell. For 
example: 

ABASIC: SHELL "list >RAM:temp lformat=%s" 
COMAL: PASS "list >RAM:temp lformat=%s" 

Such features are convenient and save you the trouble of 
using coding similar to that shown above. But my objective 
in this column is to open the door to reaching the Amiga's in- 
ner workings. So even if you know a short cut or another 
method, check out the approaches given here. ■ 

Jim Butterfield, a grizzled veteran of the microcomputer wars, has 
written about Commodore machines from theKiml to the Amiga. He 
is also the author of Machine Language for the Commodore 64, 
128, and other Commodore Computers, Write to him c/o The 
Amiga World Tech Journal, 80 Elm St., Peterborough, NH 03458. 
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even the amount of space you have for presenting the win- 
dow. You may also want to layout the gadgets again. Be- 
cause a well-behaved application needs to consider these 
anyway in the multiple-screen-resolution environment, 
screen jumping may be as simple as the lines of code above. 

FINAL TOUCHES 

There only remain a few public-screen routines provided 
by Intuition. These fall into a class of operations that are most 
likely to be performed by a public screen manager. One such 
example was provided on the Amiga Developer Conference 
disks from Atlanta. There is also a public screen manager 
called PSX making the bulletin board rounds. Unless you re- 
ally want to write a public-screen manager, you should avoid 
these routines: 

• SetDefaultPubScreen(name): Allows you to make a 

named screen the default public screen that everything open 
on. The obvious companion GetDefaultPubScreen(buf) al- 
lows the screen manager to inquire which is the default. 

• SetPubScreenModes(modes): Allows setting some glob- 
al modes that affect all public screens. Currently the only 
two modes defined are: SHANGHAI and POPPUB- 
SCREEN. SHANGHAI causes all Workbench-bound win- 
dows to be put on the default public screen instead. Note 
that some applications (such as Workbench) do not open on 
a screen as a public screen, but instead directly on the 
screen. The result is that the public screen does not get the 



window as expected. As more applications use public 
screens, this problem should diminish, POPPUBSCREEN 
causes Intuition to automatically pop a public screen to the 
front whenever a visitor window is opened on it. Lastly, no 
screen manager would be complete without the ability to list 
the public screens in the system. LockPubScreenList() re- 
turns a pointer to a List structure that can be quickly copied 
into another location. Note that there is no notification of 
any changes to the list. Also, as long as the list is locked, you 
will not be able to open any new public screens, so you 
should call UnIockPubScreenList() as soon as possible to 
avoid any deadlock situations. 

PUTTING IT ALL TOGETHER 

With 2.0, the concept of public screens allows applications 
to more tightly integrate with one another while at the same 
time eliminating much of the knowledge of each other. Creat- 
ing a public screen requires coming up with a name and pass- 
ing a new tag. Creating a visitor window for that public screen 
just requires finding a name of a window to open up on. You 
should make every effort to support jumping at the applica- 
tion level as it gives the user the ability to combine applications 
in his own way. The end result is more flexibility to the user 
and a more tightly coupled application platform. ■ 

John Toebes is the si/sopfor CompuServe's Am igaTech forum and 
was a major developer of the SAS/C system for AmigaDOS. Con- 
tact him c/o The AmigaWorld Tech Journal, 80 Elm St., Peter- 
borough, NH 03458, or on CompuServe (72230,303). 



The AW Tech journal 55 




Better Gadgets with Boopsi 



By David "Talin" Joiner 



THIS ARTICLE IS not for the faint of heart. We're going to 
delve deep into the innards of Intuition, and explore vast 
new realms untouched by the hands of application pro- 
grammers, into the dark, mysterious realm of . . . Boopsi. 

Boopsi? You may be wondering what a ridiculous name 
like Boopsi has to do with the Amiga. (I wondered the same 
thing.) Nevertheless, Boopsi is serious stuff, and stands for 
the Basic Object-Oriented Programming System for Intuition. (For 
a primer on Boopsi by its author, see "An Introduction to 
Boopsi," by Jim Mackraz, p. 38, August/September '91.) 

WHAT BOOPSI IS (OR ISN'T) 

Boopsi is a method for creating objects that can function 
much like Intuition gadgets, but with more capability. It es- 
sentially allows you to "open up" Intuition and add exten- 
sions to it. Boopsi objects can be like gadgets or images, or 
they can act like something entirely new. 

Boopsi is not an object-oriented language. It does not in- 
terface to an object-oriented language any differently than it 
would interface to any other language. Boopsi is not itself a 
language. In fact it is only "object-oriented" if you choose to 
use it in that fashion. 

At the lowest level, Boopsi consists of three things: 

1. A set of special Intuition functions for creating and man- 
aging Boopsi data structures. 

2. A set of hooks inside of the Intuition that can call user 
code. 

3. A set of standards for writing functions that will allow 
them to communicate with one another. 

This article, and the files in the accompanying disk's Join- 
er drawer, provide a complete and definitive example of a 
large and powerful Boopsi class. My intention is to provide 
you with something you can use right away. 

THE ULTIMATE SLIDER 

I confess, I'm a bit of a gadget nut, and I haven't been sat- 
isfied with cither the Intuition PropGadgets or the GadTools 
scrollers. Anybody who has used the GadTools SCROLL_ 
KIND gadgets knows what an improvement they are over the 
old approach. But, you still can't put them in window bor- 
ders and you can't make them "stretch" as a window gets big- 
ger. Consequently, I decided to design a new kind of gadget. 

I call them "Slider" or "SliderClass" gadgets to distinguish 
them from PropGadgets. Here are some of their attributes: 

• Dragging and rendering occurs in Intuition's task rather 
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than the application task so that dragging appears crisp and 
smooth regardless of what the application is doing (this rules 
out "roll-your-own" type gadgets right away). In addition, as 
the knob drags it won't flicker or flash as it redraws. 

• The arrows at the end of the slider are incorporated into the 
gadget, so the result is one single integrated gadget rather 
than three gadgets that pretend to be a single gadget, as in 
GadTools. That way, gadgets can be removed from the gad- 
get list without you knowing anything about it. 

• Numbers, or any arbitrary text, can be rendered in the knob 
of the gadget. For example, an address book program could 
be designed where the current page letter appears in the gad- 
get's knob. 

• Complete control is available over gadget appearance, such 
as borders, glyphs, patterns, and so on. But, all of these things 
default to a reasonable appearance so you don't have to mess 
with them if you don't want to. 

• The internal variables of the slider are LONGWORDs, so 
you're not limited to 64K values. Sliders can start from num- 
bers other than zero, and range to any maximum value. 

• They can be put in window borders, and they can change 
color when the window becomes active, just like the sliders 
on Workbench. 

• GRELWIDTH and GRELHEIGHT flags are used to make 
the gadget size relative to the window. 

• All the parts of the gadget communicate with each other 
without the application having to do anything. 

• Setting up a bunch of different structures to create sliders 
isn't required. All that's needed is one function call for cre- 
ation, and one for deletion. 

• They look nice and clean, with no pixels over-running the 
wrong areas. 

In addition, Boopsi offers you several other benefits "for free:" 

• Gadget attributes can be changed by the application at any 
time, without having to remove the gadget from the win- 
dow's gadget list. 

• Boopsi gadgets can actually send messages to each other in 
real time, without the application having to do anything. You 
can have a slider that tells a list to scroll, for example. 

The example in the Joiner drawer on the disk demonstrates 
the SliderClass, while a demo program exercises a number of 
its capabilities. 

FEATURES OF THE SLIDERCLASS 

The SliderClass is implemented as a file called bslider.c. 



" 



Here's a "super slider" you can tailor 
to fit your application. 



along with various support files. Because it is a private class, 
you must link SliderClass into your programs and initialize it 
by hand. First, you need to call initSliderClassQ, which ini- 
tializes the class structure and allocates some global data need- 
ed by all sliders, and returns a pointer to the newly-created 
class. (When the program exits, be sure and call freeSlider- 
ClassQ to free up this data). 

To create a slider, call the Intuition function NewObjectQ, 
passing to it the class pointer returned by initSliderClass(). 
You'll also need to pass it a TagList describing the kind of 
slider you want. The tags that are currently supported are as 
follows: 

G A_Left, GA_Width, GA_Top, GA_Height: Allow you to 

specify the dimensions of the slider's hit box. You can also use 

GAJRelRight, GA_RelWidth, GA_RelBortom, and GA_Rel- 
Height to specify a gadget that has dimensions relative to the 
window's width and height. 

GA_Image: Specifies the image class to be used as a frame 
around the slider. Important note: You must not use a nor- 
mal Intuition image, because these are fixed in size. You must 
use a custom image class or Boopsi image class that under- 
stands the IM_DRAWFRAME message. Also, if the slider 
has arrows, this frame will not be drawn around them, only 
around the actual slider container. 

GA_SelectRender: Similar to GA_Image, except that this 
frame is drawn around the actual container, rather than the 
slider's hit box. The difference between them is that the con- 
tainer is inset somewhat from (smaller than) the hit box. You 
can use a combination of GA_Image and GA_SelectRender 
to get fancy "troughs" for the slider knob to slide into (al- 
though I should note that this is contrary to Commodore's 
Amiga User Interface Style Guide (Addison-Wesley); "pushed 
in" areas are supposed to be read-only). 

GAJD, GA_UserData: Set the Gadget's ID and UserDa- 
ta, which are available for application use. 

GA_Previous: Allows you to link gadgets together as you 
create them. The address of the previous gadget in the chain 
is passed as the value of this tag item. 

G A_DrawInfo: The Drawlnfo structure obtained from the 
screen using the Intuition function GetScreenDrawInfo(). It 
is employed by the SliderClass to figure out what pen num- 
— s bers to use when drawing the gadget. 

SLD_Vertical: A Boolean value that indicates whether the 
slider is to be horizontal or vertical. (Note that 2-D sliders like 
PropGadgets are not supported. My personal feeling is that 
such 2-D gadgets should be visually distinctive enough to 
warrant a class of their own.) 



SLD_Arrows: A Boolean value indicating whether or not 
you want arrows. This tag item defaults to TRUE. 

SLD_FixBody: Indicates that you want the knob size to be 
a fixed number of pixels, rather than have it calculated on the 
fly. The tag value specifies how many pixels you want the 
knob to be. The default is 0, 

SLD_MinVal: The slider's minimum value. 

SLD_MaxVaI: The slider's maximum value. 

SLD_CurVal: The slider's current value. (I've decided to 
use my own tags here instead of the system-defined ones, 
such as PGA_TOP, because the meanings of these tags are 
slightly different.) 

SLD_Span: Corresponds to the PropGadget's BODYSIZE 
variable. It indicates how much of the range (MinVal -> Max- 
Val) should be represented by the Slider's knob size. For ex- 
ample, if MinVal is zero, and MaxVal is 30, and Span is set 
to 10, then the knob will appear to be approximately one 
third of the size of the container. 

SLDJFullRange: Normally the slider's value is limited to 
(MaxVal - Span). For example, if you have a scrolling list 
with 20 entries, and you can view five of them at a time, then 
when the slider is all the way at the bottom you should be 
looking at items 15 through 19. Thus, the slider is limited to 
values of through 15. When the SLD_FullRange flag is set, 
however, the limit is raised to MaxVal so that you can set the 
slider all the way to value 20. This is useful if the slider is be- 
ing used to represent the value of a dimensionless point. This 
tag item defaults to FALSE. 

SLD_TextHook: Allows you to specify a function call-back 
for generating the text in the slider's knob. (The default val- 
ue of NULL means "no text.") SliderClass will pass to you a 
pointer to the gadget, a structure containing the slider's cur- 
rent values, and a pointer to a buffer to fill in. You fill in the 
buffer with whatever text you want, and then return the 
length of the string that you put in the buffer. See the func- 
tion StdDigitsQ in cgsupport.c for a better example. 

SLD_KnobFont: Allows you to specify the text font that 
the KnobText (as defined by SLD_TextHook) will be ren- 
dered in. The default value of this Tagltem is the current 
mono-spaced system font. 

SLD_ArrowSize: This numeric attribute allows you to spec- 
ify how much of the slider's hit box is taken up by the arrows. 

SLD_ContInsetX, SLD^ContlnsetY: Allow you to specify 
the amount that the container rectangle will be inset from that 
gadget's hit box. Normally, these values are determined by the 
presence or absence of frame images for the slider and con- 
tainer, and whether or not the slider is horizontal or vertical. 
If you change any of those attributes, the Inset variables will « 
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be set back to their defaults, so if you do decide to have a cus- 
tom Inset setting, make sure that the SLDjContlnsetX and 
SLD_ContInsetY come after the tags for these other attributes. 

SLD_Globals: The image class structures used by the ar- 
row gadgets and the pattern for the container are stored in a 
structure called SliderGlobals. By default, the sliders will use 
a standard SliderGlobals created when the SliderClass was 
initialized. However, by using this tag item, you can substi- 
tute your own SliderGlobals structure and make the slider 
look very different. 

ICA_TARGET: As the slider is being dragged, it will 
broadcast messages indicating it's current value, ICA_TAR- 
GET specifies where those messages should be sent. The tag 
value can be either the address of another Boopsi object, or it 
can be the special value ICTARGETJDCMP, which indicates 
that the message should be sent to the window's UserPort as 
an IDCMPUPDATE message. 

ICA_MAP: As the slider sends messages, it also sends 
codes that indicate the kind of data that is being sent. These 
codes are sent in the form of tags. The slider is capable of 
sending two codes — one that is sent when the slider is drag- 
ging (SLD_CurVal) and one that is sent only after the slider 
has come to rest (SLD_FinalVal). The ICA_MAP tag lets you 
"remap" these values to any that you want. The actual"map" 
is a pointer to a tag list. Each element of the tag list is a pair 
of values — the original and the new, remapped values. 

Once the slider has been created, you will need to link it into 
your window's gadget list using AddGList(), and render it us- 
ing RefreshGList(). When you are done with the gadget, you 
can free it from the window's gadget list using RemoveG- 
List(), and free it using the Intuition call DisposeObject{). 

Getting messages from the slider is simple, just listen for 
the IDCMP event IDCMPUPDATE. Attached to this message 
will be a tag list of changes that have occurred. Each attribute 
will be identified by it's tag value, which in the case of the 
SliderClass is the same value as specified for the values spec- 
ified for ICA_MAP. 

In the demo code, 1 have two sliders in the window bor- 
ders. These sliders have been told that their output attribute 
codes are PANVAL_X for the horizontal one, and PAN- 
VAL_Y for the vertical one. PANVAL.X and PANVAL_Y 
are arbitrary numbers that I made up; the actual number 
doesn't matter, they are just codes to determine which slid- 
er the value came from. In the Intuition event loop, when an 
IDCMPUPDATE message is received, we run though the tag 
list, looking at each value. For each value seen, an appropri- 
ate action is taken. In the case of PANVAL_X and PAN- 
VAL_Y, we might store the associated slider output value 
into a variable, and then set a flag indicating that the win- 
dow's contents should be scrolled. When the "batch" of mes- 
sages from the window's UserPort is completed, we can look 
at the flag and scroll the window to the new values if it is set. 
This allows a nice smooth scrolling action, without Super- 
BitMap windows. 

Another way to get values from the slider is the Intuition 
GetAttr() function. This allows you to get the slider value at 
any time, but it is not as efficient. 

You can use SetGadgetAttrs{) to set the value of the gad- 
get, and you can use it to change other attributes of the gad- 
get as well. There is also a SetAttrsO function. The difference 
is thatSetGadgetAttrs() handles the problems associated with 
changing an attribute of a gadget that is currently attached 
to a window, and SetAttrsQ is a faster version that doesn't 



handle that. So if your gadget isn't attached to a window, or 
it is a Boopsi object that is not a gadget type, you'll want to 
use SetAttrsO instead. 

GENERAL CODE CONVENTIONS 

Before I get into the details of the SliderClass, I should ex- 
plain some of the code conventions I used. 

A handy little structure that is defined in intuition.h and 
is used to represent a rectangular region is struct IBox: 

struct IBox { 
WORD Left; 
WORD Top; 
WORD Width; 
WORD Height; 

); 

I use this structure everywhere. In fact, in my personal li- 
brary I have a bunch of functions that operate on IBoxes, 
such as intersect, shrink, and so forth. 

Another structure that I use a lot is struct ValueRange, de- 
fined in newgadgets.h : 

struct ValueRange { 
LONG Min. 

Max, 

Current, 

Span; 
}; 

I use a ValueRange structure to represent the current slider 
values, and I use them for other types of gadget classes as well. 
In this article, I'm using the term "message" fairly generi- 
cally to mean a structure that is passed to a function and that 
has a code in the structure that tells the function what kind 
of structure it is. An example of this is the opUpdate struc- 
ture found in intuition/classusr.h: 

struct opUpdate { 

ULONG MethodID; /* Message type 7 

struct Tagltem "opu AttrList; /' Tag List oi attributes to update V 

struct Gadgetlnfo *opu_Glnfo; /" Gadgetlnfo structure used to 

rerender */ 
ULONG opu_Flags; f various flags 7 

}; 

This structure is used to send an OM_UPDATE or OM_ 
NOTIFY message to a Boopsi object. The first field, Method- 
ID, would contain either the value OM_UPDATE or OM_ 
NOTIFY. 

Note that in some cases, these structures are actually built 
on the stack out of parameters. For example, to send an 
OM_UPDATE message to an object, you don't need to actu- 
ally fill in an opUpdate structure; you can build it like this: 

result = DoMethod(object, OMJJPDATE, taglist, gadgetjnfo, flags ); 

Note that each of these parameter values is pushed on the 
stack. If you take the address of the second parameter (OM_ 
UPDATE), you essentially have an opUpdate structure! This 
is exactly what DoMethod() does when it sends a message to 
your object. 

This technique only works because function calls on the 
Amiga normally push parameters as four-byte values, and 
the opUpdate structure has been designed only to use four- 
byte values. 

There is also another version of DoMethodQ, called DMQ, 
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that doesn't do it this way. Instead it expects a filled-in opUp- 
date structure (or whatever structure you may be sending) as 
it's second parameter. In addition to DM and it's associated 
functions (all of which are taken directly from the original 
Boopsi example code written by Jim Mackraz), I have my own 
version of DM(), called SendObject(), which takes advantage 
of registerized parameter calls. Fortunately, these functions 
are so tiny it doesn't hurt to have both versions linked in. 

IMPLEMENTATION OF THE SLIDERCLASS 

The first question to consider when creating a Boopsi class 
is: "what will this class's superclass be?" Under 2.0, each of 
the standard Intuition gadgets is implemented as a gadget 
class, and a customized Boopsi class should be written as a 
subclass of one of the existing classes. Each time an event is 
sent to a gadget, the gadget's class can decide to let the su- 
perclass handle the event instead. This can allow for reusing 
a lot of code. 

For example, in the case of the SliderClass, it would seem 
that because a slider is a lot like a standard Intuition Prop- 
Gadget, it would make sense to make Slider a subclass of 
PropGadget. Upon closer examination, however, I realized 
that the internals of my SliderClass had almost nothing in 
common with PropGadgets, and, in fact, several of Prop- 
Gadget's features would actually get in my way. So I chose 
instead to make SliderClass a subclass of gadgetclass, which 
is the parent class of propgadgetclass. Figure 1 shows how 
the SliderClass fits into the Boopsi class hierarchy. 

The code for the SliderClass consists of essentially four 
parts. These are described in the following paragraphs. 

RENDERING AND CALCULATING CODE 

The first part is a set of functions that draws the various 



parts of the slider, and also determines where to place the 
knob and how big the knob should be. The main functions 
are as follows: 

QuickBeveK): Draws a beveled box. You'll note that there 
are other functions for drawing beveled boxes as well, this 
one is just very simple and fast. We don't want the slider to 
hog the CPU while being dragged with the mouse, 

RenderSIiderO: Draws all the components of the slider, 
such as the container, the border frame, the knob, the arrows, 
and so on. You set flags indicating which parts you want 
drawn, because when dragging the knob with the mouse it 
isn't necessary to rerender the arrows or the border frame. 
This function also calculates what color the gadget should be, 
based on whether it and/or the window is active. To avoid 
flicker, it is careful to never draw any pixel more than once. 

CalcSIiderBodyO: Calculates the size of the slider knob, 
given such factors as the span of the slider, the size of the gad- 
get, various flags, and so on. It also ensures that the knob will 
be large enough to grab, and if there is text inside the knob, 
it figures out how big that text should be and adjusts the 
knob's size accordingly. 

CalcSliderPositionO: Once the size of the knob is deter- 
mined, this function figures out where the knob should be 
placed. Various flags and conditions can affect this calcula- 
tion, such as the size of the arrow gadgets, whether the slid- 
er is vertical or horizontal, and so on, 

SetUpContainerlnfoO: When the slider is rendered or se- 
lected, this function is called to figure out the size of the gad- 
get and the size of the knob's container. Note that in the cur- 
rent implementation, the code assumes that the window (and 
thus the gadget) will not change size while the slider is actu- 
ally being dragged. »- 
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SetUpKnoblnfoO: This function fills in a Knoblnfo struc- 
ture, which is used to hold all the temporary variables for cal- 
culating knob position and size. 

TestArrowO: This function tests to see if the mouse point- 
er is over one of the arrows. If it is, it returns the part code 
for that arrow. 

LOW-LEVEL EVENT HANDLER 

The low-level event-handler section of code handles input 
events passed to it by Intuition. These events originate in the 
input.device task, which calls Intuition's input handler. In- 
tuition converts the input events to gadget events and pass- 
es them to the handler for the currently active gadget. The 
gadget-handler code (our code, in the case of the SliderCIass) 
is free to interpret these events however it wishes. Note that 
all of this occurs in the context of the input.device task, not 
the application task, so special care is necessary, especially 
when rendering. 

There are basically five different message types that need 
to be supported: 

1. GM_HITTEST: The gadget code should return TRUE if it 
was actually hit. Note that this function should be used only 
to decide whether the gadget was actually "touched" by the 
mouse, and should not be used to decide whether to go ac- 
tive or not. That decision should be made by the GM_GOAC- 
TTVE handler. Otherwise, gadgets that are "underneath" the 
gadget (for example, a gadget that is overlapping a window 
drag bar) might be activated "through" your gadget. 

2. GM_RENDER: This is a command from Intuition to reren- 
der your gadget. 

3. GM_GOACTIVE: This is Intuition's way of letting the 
gadget know that someone has clicked on it, and that it 
should go to an active state. The gadget can return codes in- 
dicating if it should stay active (like a string gadget or REL- 
VERIFY button), or should de-activate immediately (like a 
toggle gadget or GADGETIMMEDIATE button). It can also 
refuse to go active; for example, in the case of the SliderCIass, 
if it detects that the pointer to the original InputEvent struc- 
ture is NULL (meaning that the gadget was activated from 
an ActivateGadgetf) call rather than a user action), it returns 
a code indicating that it doesn't want to go active (because 
an active slider without user manipulation makes no sense). 
Note that if the gadget does go active, it is guaranteed to get 
a GM_GOINACTIVE call eventually, so you can allocate re- 
sources on a GM_GOACTTVE and free them on a GM_GOIN- 
ACTIVE. Also, except for group gadgets, you are guaranteed 
to be the only active gadget in the system until GM_GOIN- 
ACTIVE is received. 

4. GM_HANDLEINPUT: Once the gadget has been made ac- 
tive, Intuition uses this event type to send it input events. 
Again, you can return a code to Intuition indicating whether 
you want to stay active or not. For most gadgets, you would 
want to de-activate when you get a mouse-up message. The 
GM_HANDLEINPUT routine is what really makes the gad- 
get go. 

5. GM_GOIN ACTIVE: Intuition sends this message to the 
gadget when another window or gadget has been clicked on, 
telling it that is should go inactive. 

Intuition sends messages by passing a pointer to a struc- 
ture to your low-level gadget handler. The message types 
listed above are passed in one of the structure's fields. Note 



that some of the fields in the last part of this structure may 
be different for various messages. All of the structures are de- 
fined in the include file intuition/gadgetclassh. 

The codes returned by GM_GOACTTVE and GM_HAN- 
DLEINPUT are as follows: 

GMR_MEACTI VE: Return this if you want to go active (or 
stay active if you already are). 

GMR_REUSE: Return this if you want to go inactive, and 
you want Intuition to reuse the input event. For example, 
gadgets should go inactive whenever the right mouse button 
is pressed, so that menu activity can occur. You would return 
GMR_REUSE to instruct Intuition to reuse the mouse button 
event for menu-processing. 

GMR NOREUSE: Return this if you want Intuition not to 
reuse the event. A typical case would be a mouse-up message. 

In addition, you can set the GMR_VERIFY flag in either the 
GMR_REUSE or GMR_NOREUSE codes. This instructs In- 
tuition to send a GADGETUP message to the UserPort. You 
can use this feature to implement a RELVERIFY type of 
Boolean gadget. 

HIGH-LEVEL MESSAGE HANDLER 

The high-level message handler monitors messages from 
sources other than Intuition, for example, the application or 
other Boopsi objects. Unlike the low-level handler, high-lev- 
el messages are really just function calls that can occur in ei- 
ther the Intuition task or the application task. 

High-level messages can be "inherited" from higher-level 
classes in the Boopsi inheritance tree. We can see the useful- 
ness of this just by examining the tag values that the Slider- 
Class accepts. Only the tag items that begin with SLD are ac- 
tually implemented by theSliderClass. All the others, such as 
GA_Left and ICA_TARGET are inherited from the gadget- 
class and rootclass classes. 

The high-level messages that can be sent to the object are: 

OM_NEW: Sent by the Intuition function NewObjectQ to a 
newly-created Boopsi object, telling it that it should initialize 
itself. The message structure includes a tag list of attributes 
that can be used to set the initial attributes of the gadget. 

OM_DISPOSE: A command to the object to free itself. It 
is sent when the Intuition function DisposeObject() is called 
on the object. 

OM_SET: Sent to the object whenever a SetAttrsQ or Set- 
GadgetAttrsQ call is made on the object. Like OM_NEW, the 
message contains a tag list of attributes. In the example code, 
the handlers for both OM_NEW and OM_SET call the same 
function, setSHderAttrsQ, to actually set the attributes. 

OM_GET: Sent to the gadget as a result of a GetAttr() func- 
tion call. 

OM_ADDTAIL: Each Boopsi object begins with a Min- 
Node structure. You can use this message to tell the gadget 
to add that node to a list. This is useful for keeping track of 
objects. Note that in the SliderCIass, we don't handle this 
function, the superclass does. 

OM REMO VE: The converse of OrvLADDTAIL, also han- 
dled by the superclass. 

OM_NOTIFY: This message instructs the object to broad- 
cast its current state to any other objects that may be con- 
nected to its outputs. Objects are supposed to send this mes- 
sage to themselves when an internal state change occurs as 
the result of some low-level event. For example, in the Slider- 
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Class, we send an OM_NOTIFY to ourself whenever the slid- 
er's value changes. Why not just broadcast the data directly? 
Because the OM^WOTIFY function isn't handled by the Slid- 
erClass, but rather by the superclass, gadgetclass. When we 
send an OM_NOTIFY to ourselves, along with a tag list of 
changed attributes, it actually gets passed to the OM_NOTI- 
FY handling function in the gadgetclass class, which then 
takes care of distributing the message to the correct receivers. 
Each receiver gets to look at the tag list and can take appro- 
priate action. In addition, if someone writes a subclass of 
SliderClass, that class will be able to intercept and veto or 
modify the notification message by overriding OM_NOTIFY 
in their class. 

OM_UPDATE: This message is sent to the object by other 
Boopsi objects. Its use is to allow objects to interconnect with 
each other. One Boopsi object can send an OM_UPDATE 
message to another one, telling it to update its internal fields. 
Interconnection, or "IC" objects can be built that translate the 
output of one object to a set of codes understandable by an- 
other object. In my code, OM_UPDATE and OM_SET do es- 
sentially the same thing. 

OM_ADDMEMBER, OMJIEMM EMBER: Boopsi allows 
the concept of group gadgets, in other words groups of gad- 
gets that are tightly coupled with each other. One example 
might be a "mutual exclusion group." This would function as 
a group of mutually excluding gadgets. You could use 
OM_ADDMEMBER to add gadgets to the group, and the han- 
dler code for the group could ensure that no two gadgets are 
selected at the same time. (Note: There are actually about five 
different ways to implement mutual exclusion in Boopsi!) 

One thing to note about OM„SET and OMJJPDATE is that 
they need to keep track of whether the state of the gadget 



changed, so that they can rerender the gadget if necessary. If 
the superclass makes any changes, these must be kept track 
of as well. The way to do this is as follows: Each OM_UP- 
DATE or OM_SET handler function should compute and re- 
turn a changed flag, which is TRUE if any changes were made 
that might cause a refresh. When the handler calls its super- 
class, the superclass will also return a changed flag, which 
should be combined via OR into the flag for this handler as 
well. Finally, if this handler is found at the bottom of the tree 
(by checking to see if the objects "true class" is the same as the 
class being handled by the handler function), and there were 
changes, then the handler function should cause a rerender. 
Only the bottom-most method handler should cause a reren- 
der, otherwise the gadget would be redrawn multiple times. 

SUPPORT FUNCTIONS 

The fourth section of code is the support functions, in- 
cluding the standard Boopsi functions for sending messages 
to objects and classes, as well as some useful gadget-related 
functions and miscellaneous routines. Some of these bear fur- 
ther explanation. 

Most Boopsi example code uses a "switch" statement to in- 
terpret the various message codes. Just to be different, how- 
ever, I implemented a data-driven message dispatcher. This 
small assembly language routine takes the message code 
(called the "Method ID") and uses it to look up the address 
of the function to call in a table. (Note that Method IDs aren't 
always contiguous, so there may be several tables.) If the 
function isn't in the table, it just jumps to the superclass. The 
result can be much faster than a switch statement, depend- 
ing on the messages sent. Even faster techniques are possi- 
ble, using caching. 

The C source file cgsupport.c has a bunch of useful func- ■ 
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Remove object from list 




OM_NOTIFY 


Instruct object to broadcast 
its current state 


TagList of attributes to broadcast 


OM_UPDATE 


Receive broadcast from 
another object 


TagList of attributes sent. 


OM ADDMEMBER 


Add Item to internal list 


Item to add 


OM. REMMEMBER 


Remove Item from internal list 


Item to remove 



Figure 2. Standard Boopsi messages. 
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tions for implementing custom gadgets. It contains a function 
to invoke image classes (DrawCustomFrarne()), a function to 
calculate gadget hit boxes (SetupIBoxQ), functions to help 
objects send messages to each other and to the application 
(notify AttrChangesO and updateAttrChanges()), and more. 
The following are several additional small assembly lan- 
guage files. These are generally useful functions that I have 
written or collected over the years: 

clampO: Constrains a value between minimum and maxi- 
mum limits. 

GetHeadQ: Returns the first node of an Exec list. 

NextNodet): Returns the next node of an Exec list. 

DigitCountO: Quickly calculates the number of decimal 
digits in a binary number, without taking the time to convert 
that number to decimal. 

fs2a() ("Fixed Signed to ASCII"): Quickly converts a bina- 
ry number to ASCII decimal, with a fixed number of digits. 

DrawRectO: Quickly draws a hollow rectangle by pushing 
coordinates on the stack and then calling PolyDraw(). 

Note that you don't have to implement all of this at once. 
My advice is to worry about the high-level message section 
last. First, design your structures and write a function that just 
draws the gadget. Call this function directly from your test 
application, so that you can debug it. Remember, once you 
hook it up to Intuition, you won't be able to use a debugger 
or printfQ calls (though kprintf() will work) because if you 
halt Intuition, the debugger won't run either! Also, make sure 
all of your pixels are in the right place. Then work on the low- 
level message portion, and just stuff in default values when 
the object is created. Hard-code as many things as you can, 
but bear in mind you will want to make them variables even- 
tually. Later, you can hook up routines to allow finer control 
of the gadget by the application using the high-level interface. 

Another thing to note is that some of the fields of the orig- 
inal Gadget structure are also available for your use. In Slider- 
Class, the following fields are used: 

GadgetRenden Pointer to slider frame image class. 

SelectRender Pointer to container frame image class. 

GadgetText: Pointer to knob font. 

Speciallnfo: Pointer to a Sliderlnfo structure which con- 
tains additional variables. Note that the Sliderlnfo structure 
actually follows the Gadget structure in memory. This is tak- 
en care of automatically by the class rootclass when the ob- 
ject is created. For convenience, however, I also use the Spe- 
ciallnfo pointer to point to the slider data. 

These are really about the only fields that are truly safe. 
Note that you must not use the MutualExclude field! This is 
used by Boopsi to hold a pointer to your class. NextGadget 
and other fields that are used directly by Intuition probably 
shouldn't be messed with either. 

IMAGE CLASSES 

Another module that is not actually part of the SliderClass 
but is required by the SliderClass in order to work is Boxlm- 
age. This is a Boopsi image class for drawing beveled boxes. 

Boxlmage can draw a beveled or single-color frame around 
any rectangle that is passed to it, and can also draw a glyph 
centered within the frame, such as an arrow or icon. A Box- 



Image structure (defined in newgadgets.h) is used to define 
the type of frame to be drawn and the glyph. The PlanePick 
and PlaneOnOff fields are used to define the Width and 
Height of the glyph, respectively. 

Image classes can be called either by the application, by In- 
tuition, or by a gadget class. There are a variety of messages 
that can be sent to the image class, such as IM_DRAW and 
IM_DRAWFRAME. The only difference between the two is 
that Evl_DRA W specifies that the image should use the width 
and height variables in the actual image structure, whereas 
the IM_DRAWFRAME message includes the width and 
height to be used in the message structure itself. This means 
that a single image class structure can be used by many gad- 
gets, regardless of their size. Note that Intuition only uses the 
IM_DRAW message, so you won't be able to do this trick 
with normal Intuition gadgets. 

The function DrawCustomFrameQ in cgsuppport.c can be 
used to invoke image classes. You pass it a pointer to a Rast- 
Port, a pointer to the image, an IBox which contains the rect- 
angle specifying the rectangular region to draw the frame in, 
a Drawlnfo which represents the pen colors for the screen, 
and finally the "state" that you want the image to be drawn 
in, such as "selected," "ghosted," and so on. Note that the 
pointer to the image must point to the image field in the Box- 
Image structure, not the beginning of the structure. This is be- 
cause there is a hidden object structure that comes before the 
image. The Drawlnfo is used to make sure that the bevel-box- 
es render in the correct colors, even if the screen has a non- 
standard palette. Note also that you can link several image 
classes together using the Nextlmage field, just like normal 
Intuition Images. Also, the pointer must point to the Image 
structure, not to the beginning of the Boxlmage structure. 

The SliderClass rendering code calls DrawCustomFrameQ 
for each of the arrow gadgets, using the image class pointers 
specified in the current SliderGlobals. These structures have 
the little arrow glyphs already set up by the class, however, 
you can easily replace them with your own. 

ABOUT THE DEMO 

The demo program demonstrates a couple of other note- 
worthy things besides Boopsi. For one thing, it can handle 
any number of open windows and will only exit when there 
are no windows left. (Use the New menu item to open a new 
copy of the window.) It uses a number of advanced tech- 
niques for handling: 

• Intuition messages 

• menus 

• simple-refresh windows and message ports that would be 
useful when writing a large, complex application that sup- 
ports any number of open documents 

• and any number of associated windows, open for each doc- 
ument, that share the same UserPort, and thereby have only 
a single task to deal with. 

The demo was made by paring down a large application. 
Therefore, it might make a good skeleton for future large 
applications. ■ 

David "Taltn" Joiner is the author of Miisic-X and Faery Tale 
Adventure, plus an artist, award-winning costume designer, and 
moderator of the user. interface topic of the Amiga.sw BIX confer- 
ence. Contact him c/o The AmigaWorld Tech Journal, SO Elm 
St. Peterborough, NH 03458, or on BIX (talin). 
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From p. 23 

Env(). You may also safely pass in NULL. Using the func- 
tion might take the following form: 

FreeSprRendEnv (rendenv); 

SIDE NOTES 

You might notice that Amiga sprites are interleaved bit- 
maps. Thus, interleaved BitMap structures can be created to 
describe sprites, and interleaved blits can be performed di- 
rectly into them. If you've read "Slitter Optimization" (p. 10, 
November/ December '91), you're aware of the benefits of 
this kind of blit, as well as the pitfalls. If you are unfamiliar 
with these traps, the primary rule to remember is to never 
render outside the valid area. Remember that the BitMap is 
describing a larger area than is truly valid. In particular, call- 
ing SetRast() on a sprite's RastPort is unsafe (unless a Layer 
has been attached), because SetRast() tries to write to all the 
bits described in the BitMap. 

The routine GetSprRendEnv() currently does not handle 
16-color sprites, but could easily be extended to support 
them. The operations are precisely the same, except that plane 
pointers two and three are filled in with pointers into the sec- 
ond sprite. This might appear as follows: 

struct Simple Sprite *spr1, "spr2; 
struct BitMap 'spritebm; 
PLANEPTR spritedata; 

InhBitMap (spritebm, 4, 32, spr1-> height); 



spritedata = (PLANEPTR) spr1->posctldata; 
spritebm->Plane[0] = spritedata + 4; 
spritebm->Plane[1] = spritedata + 6; 
spritedata = (PLANEPTR) spr2->posctldata; 
spritebm->Plane[2] = spritedata + 4; 
sprltebm->Plane[3] = spritedata + 6; 



WINDING DOWN 

The book of the month is The Wizardry Cursed by Rick 
Cook. My son, Alex, and I have both read it and think it's 
marv... Oh! Sorry, wrong column. 

Rendering into sprites has a number of advantages. For ex- 
ample, sprites could be used to display textual information 
cleanly on a HAM screen. Sprites can live on top of double- 
buffered displays without additional programming, enabling 
you to display limited information while an animation is in 
progress. They can also be used to peacefully display global 
information on top of all screens, such as the current time of 
day, total available memory, the open count on a shared li- 
brary, or something else of interest. Hopefully, these tech- 
niques will add to the tools at your command to help you cre- 
ate exactly the application you want. ■ 

Leo L. Schwab was the principal programmer behind Disney 
Presents.. . The Animation Studio and has created many PD screen 
hacks. He can frequently be seen at computer shows wearing a cape 
and terrorizing IBM reps. Contact him c/o The AmigaWorld 
Tech Journal, 80 Elm St., Peterborough, NH 03458, or on BIX 
(eiuhac), Portal (ewhac), or Usenet (ezoliac@iuell.sf.ca.us). 
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From p. 28 

namically allocate CallNodes — the LocalData might be a 
pointer back to the CallNode or to some other data structure 
associated with this particular CallNode. 

There are several other functions provided in the library 
that add additional functionality to the system and make it 
useful for applications other than refreshing. 

The function RemCallNodeQ is exactly the opposite of Add- 
CaIlNode() — it removes a CallNode from a CallList without 
actually calling the function. Simply call it as you would 
Exec's Remove() function. As you can AddCallNode(), you 
can safely call tliis function with a CallNode that was not pre- 
viously on any list. (See the source code on disk for the actu- 
al definition of tliis function.) 

Finally, if you want to call all of the CallNodes in a Call- 
List, but leave the list intact so you can later use the same list 
again, just use the CallQ function. In this case, an explicit call 
to RemCallNode() is required to remove a CallNode. This 
will generally not be useful for refreshing, but may be useful 
in other applications of this system. 

If you use this variation, you should not call AddCall- 
Node() from within the CallFunctions, because newly added 
nodes may be accidentally skipped (even if they have a low- 
er priority than the current node). You should also not call 
RemCallNode() on other nodes in the same list from within a 
CallFunction. However, you may RemCallNodeQ the current 
node from within its own function, to indicate that that func- 
tion doesn't need to be called anymore. 

There are also two variations of Calif) and CallRemQ, 



named CallExtQ and CallRemExt(), respectively. These vari- 
ations accept the same arguments as the regular versions, 
plus an extra parameter: a pointer to a function to call after 
each CallFunction on the list is called. You can use this facil- 
ity, for example, to check for such signals as CTRL-C while 
the list is being processed. See the source code on disk for 
more details about these functions. 

By now, you have probably noticed that CallLists can be 
used for applications other than display refreshing. For ex- 
ample, during your program you can maintain a CallList that 
is called only once, when your program is about to exit. When 
a module in your program allocates some memory or opens 
a window, it simply adds a CallNode to this global CallList. 
When the program is about to exit, this CallNode will auto- 
matically be called, so the module can free anything it pre- 
viously allocated. 

Using CallLists can help make screen refreshing elegant 
and efficient. Unnecessary processing is eliminated and inter- 
dependencies can be handled easily. Because the CallList li- 
brary functions use no global variables, they can be reused 
as much as necessary in one program, and will cause no prob- 
lems (if used correctly) in re-entrant code such as run-time li- 
braries. Remember, CallLists are useful for many purposes, 
display refreshing is just one of them. ■ 

Bryan Ford is a student at the University of Utah and works on 
freelance programming projects for local companies. Contact him 
c/o The AmigaWorld Tech Journal, 80 Elm St., Peterborough, 
NH 03458, or on Internet (bryan.ford@m.cc.utah.edu). 
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Flames, suggestions, and cheers from readers. 



A FAILED LAUNCH 

After reading Marvin Weinstein's 
"Extending ARexx" (October '91, p. 
18), I tried modifying fastmenu to 
launch SID and Uedit, which do not 
reliably launch from AmiDock. So I 
wrote the following program: 



call AddGadget{CIIckLIst,6,28,EW..3.0," 
EasyWrlter_3.0 ", , 

'"address command run TOOLS:Ue_3.n, ■ 

ds:Data!_3.Q'" 
call AddGadget(ClickList,6,41 ,WP," Word- 
Perfect 4.1 ", , 

'"address command run TOOLS:Word- 

Perfect/wp'" 

I added the WordPerfect gadget 
because WP launches reliably from 
AmiDock. However, I was surprised 
to find that, just like SID and Uedit, 
WP does not launch at all. Did I mis- 
understand something? The logic of 
this is so straightforward. ' 

Robert A. Jenkins, Ph.D. 
Miller Woods, Illinois 

"The problem lies not in the logic Dr. 
Jenkins but in the quoting." This point 
was covered implicitly in "ARexx Arcana, 
Hosts and Quotes" (August/September 
'91, p. 2), but merits further explanation. 
If we look at the call to AddGadgetO used 
in your ClickList program we see that the 
string: 

'"address command run TOOLS:Word- 
Perfect/wp '" 

is parsed once by ARexx. At this time 
ARexx removes the first set of quotes and 
notifies your rexxarplib host to send the 
string program: 

'address command run TOOLS:Word- 
Perfeclwp ' 

to ARexx for processing. Wlten ARexx 
gets this string it parses off the single 
quotes (because they tells it that this is a 
string program) and then attempts to 
interpret the line: 



address command run TOOLS:Word- 

Perfect/wp 

Here things break for a variety of rea- 
sons. First, ARexx treats a line which 
begins with a TOOLS:... as a label, which 
this line is not. Next, it finds two vari- 
ables, WordPerfect (which it automatically 
uppercases to WORDPERFECT) and wp 
(which it converts to WP). If then, tlurnks 
to the I, attempts to divide these undefined 
variables, producing an error message. 
1 (Try this line out in an ARexx program to 
be run from a CU and see the error mes- 
sage that results.) The same problem 
appears in all of your calls to AddCadget. 
To get something that works you would 
type: 

address command run "TOOLS:Word- 
Perfeet/wp" 

because the quotes ivould keep ARexx 
from interpreting the quoted material 
before passing the command to Amiga- 
DOS. You mitst use more quotes in your 
call to get this string passed to your host. 
The correct form of the call is: 

call AddGadgei(ClickList,6,41,WP," Word- 
Perfect 4.1",, 

'"address command run '"TOOLSrWord- 

Perlect/wp'"" " 

In this case the outermost double quotes 
are parsed off when the message is sent to 
the rexxarplib host and, at the same time, 
the innermost "" are converted to " , 
Wlien the string program is sent to 
ARexx the outermost single quotes disap- 
pear and ARexx attempts to interpret a 
viable one-line program. 

It is also safer, if you are going to use 
fanny gadget names such as UE_3.0 to 
enclose them in quotes inside the call to 
AddGadgetO to avoid similar problems. 

Marvin Weinstein 

JOYSTICK RESPONSE 

This letter is in response to Tony 
Gore's letter ("A Challenge," Novem- 
ber/December '91). A joystick may 
have three buttons, just like a mouse. 
In fact, the computer cannot tell a 
joystick from a mouse except that a 
joystick cannot generate the proper 
quadrature signals to increment the 



mouse counters. Secondly, there are 
three-button joysticks available for the 
Amiga: Go to a video game retailer 
and buy a joystick for the Sega Gene- 
sis. (I recommend the Sega Genesis 
Arcade PowerStick.) These joysticks 
are completely Amiga compatible and 
have three buttons. Finally, there are 
some software developers who al- 
ready write software for joysticks with 
more than one button. If you try out R- 
TYPE with a Genesis joystick, you will 
find that the program uses two of the 
three buttons (one to fire and one to 
separate the expansion from the ship). 
I agree that more software needs to 
support multiple fire buttons, but a 
new joystick standard is not the an- 
swer. Joystick manufacturers just need 
to quit making single-button joysticks 
and use the joystick specification more 
fully, as did Sega. 

Joseph Fenton 
Barker, Texas 



WANTED ADA 

I am studying mathematics and 
computer science at a college in Swe- 
den. In computer science classes we 
are using Ada. I think Ada is a good 
programming language, and I've 
heard it is making good progress. I 
encourage developers to develop an 
Ada programming environment for 
the Amiga. But hurry! In two years I 
will start to develop one myself. 

Pahik Johansson 
Alvesla, Sweden 

LET US KNOW 

Wltat are your suggestions, complaints, 
and hints for the magazine, Amiga devel- 
opers, and your fellow readers? Tell us 
about them by writing to Letters to the 
Editor, The Amiga World Tech Journal, 
80 Elm St., Peterborough, NH 03458, or 
posting messages in the AW. Tech Journal 
conference on BIX. Letters and messages 
may be edited for space and clarity. ■ 
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,ook Inside the Ultimate 4500, 




[CD proudly presents Prima."., the high performance, 
low cost hard drive for Amiga" 500 computers. Prima 
blends a large capacity, low power Quantum " hard drive 
with the AdIDK" host adapter for an unbeatable 
combination. 

Prima replaces the internal floppy drive but includes 
Shuffle Board " to make your external floppy drive 
DFO:. Prima features auto-booting from FastFileSysiem 
partitions, high speed caching, auto-configuring, and 
A-MaxII" support. Formatted capacities of 52 and 105 
megabytes are currently available. 



Prima comes complete with instructions, software, and 
all the hardware necessary for a simple, clean, no-solder 
installation, It does require an A500 with switching 
power supply, I megabyte of RAM. and an external 
floppy drive for setup and installation. 

What other products would we include in the "Ultimate 
A300"? Of course a four megabyte AdRA.YT 540 and 
Flicker Free Video'" with a multi-sync monitor. 
Whv settle for less? 



~ 



ICD 



ICD, Incorporated 
1 220 Rock Street 
Rockford, Illinois 61 101 
USA (815) 968-2228 Phone 



(800) 373-7700 Orders (815) 968-6888 FAX 



Prima, AdlDE, AdRAM. Flicker Free Video, nnd ShuFfle Eocrd ere rrodemoAs o! CD, Irw Other brond and product name* ore recjiiltered trademarks or trademarks, of rheir rasped** holdec* 
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TAKE THIS JOB AND LOVE IT! 



The fastest growing video technology 
company in the world is looking for technical 
support specialists. We're looking for the kind 
of person that enjoys solving problems. If you 
have the unique ability to; hear a problem, ask 
the right questions, analyze the answers, and 
then provide a perfect solution, you belong 
with NewTek. You'll be a key member of the 
best support team in the business. Best of all. 
you'll be working for a company that has an 
intense commitment to serving its customers. 

We're looking for rare individuals with as 
many of the following qualities as possible: 

• Excellent written and verbal communication 
skills 

• Experience in video production and editing 

• Knowledge of 3D animation and computer 
graphics 



• Knowledge of Amiga software and peripherals 

• Experience with Digi-View and Digi-Paint 

• Experience with the Video Toaster 

• Work experience in the technical support field 

The Video Toaster is changing the way 
the world thinks about video production. The 
Toaster is being used everywhere from net- 
works to cable stations and our users range 
from rock stars to wedding videographers. 
Helping producers, artists, and video makers 
use this powerful tool to revolutionize video 
is an exciting and rewarding career. If you're 
ready to make a change for the better call 
Kiki Stockhammer at 913-354-1146. 



215 S.E. Eighth St. 
Topeka. KS 66603 
913-354-1146 
FAX: 913-354-1584 



NewTek 

INCORPORATED 



